sonilo-cli 0.4.0__tar.gz → 0.7.0__tar.gz

{sonilo_cli-0.4.0 → sonilo_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sonilo-cli
-Version: 0.4.0
+Version: 0.7.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.11,>=0.10.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: respx>=0.21; extra == 'dev'
@@ -41,6 +41,8 @@ or pass `--api-key sk-...` on any command.
     sonilo video-to-sfx --video clip.mp4 --segments @segments.json
     sonilo video-to-sound --video clip.mp4 \
         --music-prompt "uplifting orchestral score" --sfx-prompt "match the on-screen action"
+    sonilo video-to-video-music --video clip.mp4 --prompt "tense synths" --output scored.mp4
+    sonilo video-to-video-sfx --video clip.mp4 --segments @segments.json --output scored.mp4
     sonilo video-to-video-sound --video clip.mp4 --music-prompt "tense synths"
     sonilo dubbing --video-url https://example.com/clip.mp4 --languages es,fr --output dubbed.mp4
     # writes dubbed.es.mp4 and dubbed.fr.mp4
@@ -50,7 +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`,
-  `--isolate-vocals`, and `--preserve-speech` 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,7 +75,7 @@ The two segment shapes are **not** interchangeable:
 | Shape | Commands | Fields |
 | --- | --- | --- |
 | Music | `text-to-music`, `video-to-music` | `{start, prompt, label?}` |
-| SFX | `video-to-sfx`, `video-to-sound`, `video-to-video-sound` | `{start, end, prompt}` |
+| SFX | `video-to-sfx`, `video-to-video-sfx`, `video-to-sound`, `video-to-video-sound` | `{start, end, prompt}` |
 
 - `start` / `end` are seconds from the start of the track or clip.
 - Passing one shape to a command that takes the other is rejected before any request is made, with
@@ -83,6 +86,48 @@ The two segment shapes are **not** interchangeable:
 - Keys the CLI does not recognise are forwarded as-is, so a newly added API field works without
   upgrading the CLI.
 - `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`
+and `video-to-sfx`: same generation, but what comes back is the source picture with the new audio
+already muxed in, so there is nothing to line up afterwards. Both are async-only and write a single
+file (default `output.mp4`):
+
+    sonilo video-to-video-music --video clip.mp4 --prompt "tense synths" --output scored.mp4
+    sonilo video-to-video-sfx --video clip.mp4 \
+        --segments '[{"start":0,"end":5,"prompt":"footsteps on gravel"}]' --output scored.mp4
+
+- `--prompt` is optional on both; without it the model scores from the picture alone.
+- `video-to-video-music` also takes `--preserve-speech`, which keeps source speech in the mix;
+  omitting it leaves the server default untouched. `--isolate-vocals` is a legacy alias for the
+  same flag — the API ORs the two together, and this endpoint returns one muxed video with no
+  separate vocals stem.
+- `video-to-video-sfx` takes `--segments` in the SFX shape `{start, end, prompt}` — see
+  [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
 
@@ -107,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.4.0 → sonilo_cli-0.7.0}/README.md

@@ -25,6 +25,8 @@ or pass `--api-key sk-...` on any command.
     sonilo video-to-sfx --video clip.mp4 --segments @segments.json
     sonilo video-to-sound --video clip.mp4 \
         --music-prompt "uplifting orchestral score" --sfx-prompt "match the on-screen action"
+    sonilo video-to-video-music --video clip.mp4 --prompt "tense synths" --output scored.mp4
+    sonilo video-to-video-sfx --video clip.mp4 --segments @segments.json --output scored.mp4
     sonilo video-to-video-sound --video clip.mp4 --music-prompt "tense synths"
     sonilo dubbing --video-url https://example.com/clip.mp4 --languages es,fr --output dubbed.mp4
     # writes dubbed.es.mp4 and dubbed.fr.mp4
@@ -34,7 +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`,
-  `--isolate-vocals`, and `--preserve-speech` 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`.
 
@@ -56,7 +59,7 @@ The two segment shapes are **not** interchangeable:
 | Shape | Commands | Fields |
 | --- | --- | --- |
 | Music | `text-to-music`, `video-to-music` | `{start, prompt, label?}` |
-| SFX | `video-to-sfx`, `video-to-sound`, `video-to-video-sound` | `{start, end, prompt}` |
+| SFX | `video-to-sfx`, `video-to-video-sfx`, `video-to-sound`, `video-to-video-sound` | `{start, end, prompt}` |
 
 - `start` / `end` are seconds from the start of the track or clip.
 - Passing one shape to a command that takes the other is rejected before any request is made, with
@@ -67,6 +70,48 @@ The two segment shapes are **not** interchangeable:
 - Keys the CLI does not recognise are forwarded as-is, so a newly added API field works without
   upgrading the CLI.
 - `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`
+and `video-to-sfx`: same generation, but what comes back is the source picture with the new audio
+already muxed in, so there is nothing to line up afterwards. Both are async-only and write a single
+file (default `output.mp4`):
+
+    sonilo video-to-video-music --video clip.mp4 --prompt "tense synths" --output scored.mp4
+    sonilo video-to-video-sfx --video clip.mp4 \
+        --segments '[{"start":0,"end":5,"prompt":"footsteps on gravel"}]' --output scored.mp4
+
+- `--prompt` is optional on both; without it the model scores from the picture alone.
+- `video-to-video-music` also takes `--preserve-speech`, which keeps source speech in the mix;
+  omitting it leaves the server default untouched. `--isolate-vocals` is a legacy alias for the
+  same flag — the API ORs the two together, and this endpoint returns one muxed video with no
+  separate vocals stem.
+- `video-to-video-sfx` takes `--segments` in the SFX shape `{start, end, prompt}` — see
+  [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
 
@@ -91,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.4.0 → sonilo_cli-0.7.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sonilo-cli"
-version = "0.4.0"
+version = "0.7.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.10.0,<0.11"]
 keywords = ["sonilo", "cli", "music", "sfx", "text-to-music", "video-to-music", "ai"]
 
 [project.urls]

{sonilo_cli-0.4.0 → sonilo_cli-0.7.0}/src/sonilo_cli/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "0.4.0"
+__version__ = "0.7.0"
 
 __all__ = ["__version__"]

{sonilo_cli-0.4.0 → sonilo_cli-0.7.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,
@@ -312,13 +339,25 @@ 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,
     )
-    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:
@@ -329,6 +368,49 @@ def cmd_video_to_video_sound(client: Sonilo, args: argparse.Namespace) -> None:
     _run_sound(client, args, client.video_to_video_sound, "mp4")
 
 
+def _run_video(args: argparse.Namespace, resource: Any, **params: Any) -> None:
+    """Run one of the video-returning endpoints and save the result.
+
+    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)
+
+
+def cmd_video_to_video_music(client: Sonilo, args: argparse.Namespace) -> None:
+    _run_video(
+        args,
+        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.
+        preserve_speech=True if args.preserve_speech else None,
+        isolate_vocals=True if args.isolate_vocals else None,
+        variants_num=args.variants,
+    )
+
+
+def cmd_video_to_video_sfx(client: Sonilo, args: argparse.Namespace) -> None:
+    _run_video(
+        args,
+        client.video_to_video_sfx,
+        prompt=args.prompt,
+        segments=_segments(args),
+    )
+
+
 # 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
@@ -425,6 +507,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__)
@@ -446,10 +539,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")
@@ -458,14 +552,19 @@ 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("--isolate-vocals", dest="isolate_vocals", action="store_true",
-                       help="Split out a vocals-only stem. 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:
+    # `isolate_vocals = bool(preserve_speech) or bool(isolate_vocals)`), so
+    # the two flags are one feature under two names, not two behaviours.
+    # isolate_vocals is the legacy name kept for existing callers.
+    p_v2m.add_argument("--isolate-vocals", dest="isolate_vocals", action="store_true",
+                       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")
@@ -504,8 +603,37 @@ 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(
+        "video-to-video-music", help="Generate music muxed into the source video"
+    )
+    _add_global(p_v2vm)
+    _add_video_source(p_v2vm)
+    p_v2vm.add_argument("--prompt", default=None, help="Optional creative direction.")
+    p_v2vm.add_argument("--preserve-speech", dest="preserve_speech", action="store_true",
+                        help="Keep source 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
+    # vocals stem in the result — the output is one muxed video.
+    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(
+        "video-to-video-sfx", help="Generate sound effects muxed into the source video"
+    )
+    _add_global(p_v2vfx)
+    _add_video_source(p_v2vfx)
+    p_v2vfx.add_argument("--prompt", default=None, help="Optional creative direction.")
+    _add_segments(p_v2vfx, SFX_SHAPE)
+    p_v2vfx.add_argument("--output", default=None, help="Where to save the scored video.")
+    p_v2vfx.set_defaults(func=cmd_video_to_video_sfx)
+
     p_v2vsd = sub.add_parser(
         "video-to-video-sound", help="Generate matched music+sfx muxed into the source video"
     )
@@ -523,6 +651,7 @@ def build_parser() -> argparse.ArgumentParser:
     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.4.0 → sonilo_cli-0.7.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)
@@ -764,7 +845,7 @@ def test_segments_semantic_rules_are_left_to_the_server():
 
 @pytest.mark.parametrize(
     "command",
-    ["text-to-music", "video-to-music", "video-to-sfx",
+    ["text-to-music", "video-to-music", "video-to-sfx", "video-to-video-sfx",
      "video-to-sound", "video-to-video-sound"],
 )
 def test_segments_help_shows_all_three_value_forms(command, capsys):
@@ -778,10 +859,224 @@ def test_segments_help_shows_all_three_value_forms(command, capsys):
 
 @pytest.mark.parametrize("command", ["text-to-sfx"])
 def test_commands_without_segments_reject_the_flag(command, capsys):
-    """text-to-sfx takes no segments in the SDK, so the CLI must not offer it
-    (video-to-video-music, the other segment-less endpoint, has no CLI
-    command at all)."""
+    """text-to-sfx takes no segments in the SDK, so the CLI must not offer it.
+    The other segment-less endpoint, video-to-video-music, is covered by
+    test_video_to_video_music_rejects_segments (it takes no --duration)."""
     with pytest.raises(SystemExit) as exc:
         run([command, "--prompt", "x", "--duration", "3", "--segments", "[]"])
     assert exc.value.code == 1
     assert "unrecognized arguments" in capsys.readouterr().err
+
+
+# --- video-to-video-music / video-to-video-sfx ---------------------------
+#
+# Both return the source picture with the generated audio muxed in, so the
+# task body carries a single `video` object rather than `audio`/`output_url`
+# (shape confirmed against tests/test_video_to_video.py in the SDK repo).
+
+
+def _video_body(task_id, task_type):
+    return {
+        "task_id": task_id,
+        "type": task_type,
+        "status": "succeeded",
+        "video": {"url": f"https://r2.example.com/{task_id}.mp4",
+                  "content_type": "video/mp4", "file_size": 7},
+        "duration_seconds": 4.0,
+    }
+
+
+def _mock_video_task(endpoint, task_id, task_type, content=b"MP4DATA"):
+    """Wire up submit + poll + download for one video-returning endpoint."""
+    route = respx.post(f"{BASE}/v1/{endpoint}").mock(
+        return_value=httpx.Response(202, json={"task_id": task_id, "status": "processing"})
+    )
+    respx.get(f"{BASE}/v1/tasks/{task_id}").mock(
+        return_value=httpx.Response(200, json=_video_body(task_id, task_type))
+    )
+    respx.get(f"https://r2.example.com/{task_id}.mp4").mock(
+        return_value=httpx.Response(200, content=content)
+    )
+    return route
+
+
+@respx.mock
+def test_video_to_video_music_saves_the_scored_video(tmp_path):
+    route = _mock_video_task("video-to-video-music", "vm1", "video_to_video_music")
+    out = tmp_path / "scored.mp4"
+    run(["video-to-video-music", "--video-url", "http://x/y.mp4",
+         "--prompt", "tense synths", "--output", str(out)])
+    assert route.called
+    assert out.read_bytes() == b"MP4DATA"
+    body = unquote_plus(route.calls.last.request.content.decode())
+    assert "video_url=http://x/y.mp4" in body
+    assert "prompt=tense synths" in body
+
+
+@respx.mock
+def test_video_to_video_music_defaults_to_mp4(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    _mock_video_task("video-to-video-music", "vm2", "video_to_video_music")
+    run(["video-to-video-music", "--video-url", "http://x/y.mp4"])
+    assert (tmp_path / "output.mp4").read_bytes() == b"MP4DATA"
+
+
+@respx.mock
+def test_video_to_video_music_flags_reach_the_request_body(tmp_path):
+    route = _mock_video_task("video-to-video-music", "vm3", "video_to_video_music")
+    run(["video-to-video-music", "--video-url", "http://x/y.mp4",
+         "--preserve-speech", "--isolate-vocals", "--output", str(tmp_path / "s.mp4")])
+    body = route.calls.last.request.content.decode()
+    assert "preserve_speech=true" in body
+    assert "isolate_vocals=true" in body
+
+
+@respx.mock
+def test_video_to_video_music_unset_flags_are_omitted(tmp_path):
+    route = _mock_video_task("video-to-video-music", "vm4", "video_to_video_music")
+    run(["video-to-video-music", "--video-url", "http://x/y.mp4",
+         "--output", str(tmp_path / "s.mp4")])
+    # Unset switches must forward None, not False, so the server default
+    # stands — same rule as --no-ducking on the sound commands.
+    body = route.calls.last.request.content.decode()
+    assert "preserve_speech=" not in body
+    assert "isolate_vocals=" not in body
+    assert "prompt=" not in body
+
+
+def test_video_to_video_music_requires_a_video_source():
+    with pytest.raises(SystemExit) as exc:
+        run(["video-to-video-music", "--prompt", "x"])
+    assert exc.value.code == 1
+
+
+def test_video_to_video_music_rejects_both_sources():
+    with pytest.raises(SystemExit) as exc:
+        run(["video-to-video-music", "--video", "a.mp4", "--video-url", "http://x/y.mp4"])
+    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."""
+    with pytest.raises(SystemExit) as exc:
+        run(["video-to-video-music", "--video-url", "http://x/y.mp4", "--segments", "[]"])
+    assert exc.value.code == 1
+    assert "unrecognized arguments" in capsys.readouterr().err
+
+
+@respx.mock
+def test_video_to_video_sfx_saves_the_scored_video(tmp_path):
+    route = _mock_video_task("video-to-video-sfx", "vf1", "video_to_video_sfx")
+    out = tmp_path / "scored.mp4"
+    run(["video-to-video-sfx", "--video-url", "http://x/y.mp4",
+         "--prompt", "footsteps", "--output", str(out)])
+    assert route.called
+    assert out.read_bytes() == b"MP4DATA"
+    body = unquote_plus(route.calls.last.request.content.decode())
+    assert "video_url=http://x/y.mp4" in body
+    assert "prompt=footsteps" in body
+
+
+@respx.mock
+def test_video_to_video_sfx_defaults_to_mp4(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    _mock_video_task("video-to-video-sfx", "vf2", "video_to_video_sfx")
+    run(["video-to-video-sfx", "--video-url", "http://x/y.mp4"])
+    assert (tmp_path / "output.mp4").read_bytes() == b"MP4DATA"
+
+
+@respx.mock
+def test_video_to_video_sfx_segments_reach_the_request_body(tmp_path):
+    route = _mock_video_task("video-to-video-sfx", "vf3", "video_to_video_sfx")
+    run(["video-to-video-sfx", "--video-url", "http://x/y.mp4",
+         "--segments", json.dumps(SFX_SEGMENTS), "--output", str(tmp_path / "s.mp4")])
+    assert _sent_segments(route) == SFX_SEGMENTS
+
+
+@respx.mock
+def test_video_to_video_sfx_omitting_segments_sends_no_field(tmp_path):
+    route = _mock_video_task("video-to-video-sfx", "vf4", "video_to_video_sfx")
+    run(["video-to-video-sfx", "--video-url", "http://x/y.mp4",
+         "--output", str(tmp_path / "s.mp4")])
+    assert b"segments" not in route.calls.last.request.content
+
+
+def test_video_to_video_sfx_rejects_music_shaped_segments(capsys):
+    with pytest.raises(SystemExit) as exc:
+        run(["video-to-video-sfx", "--video-url", "http://x/y.mp4",
+             "--segments", json.dumps(MUSIC_SEGMENTS)])
+    assert exc.value.code == 1
+    err = capsys.readouterr().err
+    assert "video-to-video-sfx segments take {start, end, prompt}" in err
+    assert "got an object with keys start, label, prompt" in err
+
+
+def test_video_to_video_sfx_requires_a_video_source():
+    with pytest.raises(SystemExit) as exc:
+        run(["video-to-video-sfx", "--prompt", "x"])
+    assert exc.value.code == 1
+
+
+def test_video_to_video_sfx_rejects_both_sources():
+    with pytest.raises(SystemExit) as exc:
+        run(["video-to-video-sfx", "--video", "a.mp4", "--video-url", "http://x/y.mp4"])
+    assert exc.value.code == 1
+
+
+@pytest.mark.parametrize("command", ["video-to-music", "video-to-video-music"])
+def test_isolate_vocals_is_documented_as_an_alias(command, capsys):
+    """Both endpoints OR the two fields into one behaviour server-side
+    (video_to_music.py: `isolate_vocals = bool(preserve_speech) or
+    bool(isolate_vocals)`; video_to_video.py: `keep_speech = bool(...) or
+    bool(...)`), so the help must not present --isolate-vocals as a separate
+    feature. On video-to-video-music there is no stem at all — the result is
+    a single muxed video."""
+    with pytest.raises(SystemExit):
+        main([command, "--help"])
+    help_text = capsys.readouterr().out
+    assert "Legacy alias for --preserve-speech" in help_text
+    assert "vocals-only stem" not in help_text
+
+
+@pytest.mark.parametrize(
+    "command", ["video-to-video-music", "video-to-video-sfx"]
+)
+def test_video_to_video_commands_are_listed_in_top_level_help(command, capsys):
+    """Both are documented publicly as `sonilo <command>`, so they have to be
+    discoverable from `sonilo --help`, not just by knowing the name."""
+    with pytest.raises(SystemExit):
+        main(["--help"])
+    assert command in capsys.readouterr().out