sonilo-cli 0.8.2__tar.gz → 0.10.0__tar.gz

{sonilo_cli-0.8.2 → sonilo_cli-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sonilo-cli
-Version: 0.8.2
+Version: 0.10.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.12,>=0.11.0
+Requires-Dist: sonilo<0.13,>=0.12.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: respx>=0.21; extra == 'dev'
@@ -106,6 +106,17 @@ request — and values above 1 are never covered by the free trial.
 - On `video-to-sound` / `video-to-video-sound`, `--stem` is applied per variant too, e.g.
   `take.0.music.m4a`.
 
+### Prompt influence
+
+`--prompt-influence` (0-1, API default 0.5) sets how strongly the generated music follows the
+prompt, on `video-to-music` and `video-to-video-music` only. Lower values let the video lead;
+higher values follow the prompt more literally. It is free of charge, and unlike `--format wav` it
+does not force the async path — it works on the streaming default too. Left unset, the field is
+not sent at all and the API's own 0.5 default applies; `--prompt-influence 0` is a real value
+("let the video lead entirely") and is sent. Out-of-range values earn a `422` from the API.
+
+    sonilo video-to-music --video clip.mp4 --prompt "tense synths" --prompt-influence 0.8
+
 ### Scored video
 
 `video-to-video-music` and `video-to-video-sfx` are the video-out counterparts of `video-to-music`
@@ -128,6 +139,8 @@ file (default `output.mp4`):
 - 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.
+- `video-to-video-music` also takes `--prompt-influence` — see
+  [Prompt influence](#prompt-influence) above. `video-to-video-sfx` does not.
 
 ### Combined soundtracks
 
@@ -146,8 +159,10 @@ they differ only in what comes back: `video-to-sound` writes the mixed **audio**
 - `--segments` places individual effects on the timeline, in the SFX shape `{start, end, prompt}` —
   see [Segments](#segments).
 - `--preserve-speech` keeps speech from the source video in the mix.
-- **Ducking is on by default** (music dips under speech). Pass `--no-ducking` to opt out — omitting
-  the flag leaves the server default untouched.
+- **Ducking is off by default.** Pass `--ducking` to bring the source video's own speech into the
+  mix with the generated bed dipped under it — without it the result is the generated music and
+  effects alone. Omitting both flags leaves the server default untouched; `--no-ducking` still
+  works and now just states that default explicitly.
 - `--stem` is repeatable (`music`, `music_processed`, `sfx`) and saves the individual layers next to
   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`

{sonilo_cli-0.8.2 → sonilo_cli-0.10.0}/README.md

@@ -90,6 +90,17 @@ request — and values above 1 are never covered by the free trial.
 - On `video-to-sound` / `video-to-video-sound`, `--stem` is applied per variant too, e.g.
   `take.0.music.m4a`.
 
+### Prompt influence
+
+`--prompt-influence` (0-1, API default 0.5) sets how strongly the generated music follows the
+prompt, on `video-to-music` and `video-to-video-music` only. Lower values let the video lead;
+higher values follow the prompt more literally. It is free of charge, and unlike `--format wav` it
+does not force the async path — it works on the streaming default too. Left unset, the field is
+not sent at all and the API's own 0.5 default applies; `--prompt-influence 0` is a real value
+("let the video lead entirely") and is sent. Out-of-range values earn a `422` from the API.
+
+    sonilo video-to-music --video clip.mp4 --prompt "tense synths" --prompt-influence 0.8
+
 ### Scored video
 
 `video-to-video-music` and `video-to-video-sfx` are the video-out counterparts of `video-to-music`
@@ -112,6 +123,8 @@ file (default `output.mp4`):
 - 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.
+- `video-to-video-music` also takes `--prompt-influence` — see
+  [Prompt influence](#prompt-influence) above. `video-to-video-sfx` does not.
 
 ### Combined soundtracks
 
@@ -130,8 +143,10 @@ they differ only in what comes back: `video-to-sound` writes the mixed **audio**
 - `--segments` places individual effects on the timeline, in the SFX shape `{start, end, prompt}` —
   see [Segments](#segments).
 - `--preserve-speech` keeps speech from the source video in the mix.
-- **Ducking is on by default** (music dips under speech). Pass `--no-ducking` to opt out — omitting
-  the flag leaves the server default untouched.
+- **Ducking is off by default.** Pass `--ducking` to bring the source video's own speech into the
+  mix with the generated bed dipped under it — without it the result is the generated music and
+  effects alone. Omitting both flags leaves the server default untouched; `--no-ducking` still
+  works and now just states that default explicitly.
 - `--stem` is repeatable (`music`, `music_processed`, `sfx`) and saves the individual layers next to
   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`

{sonilo_cli-0.8.2 → sonilo_cli-0.10.0}/pyproject.toml

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

{sonilo_cli-0.8.2 → sonilo_cli-0.10.0}/src/sonilo_cli/__init__.py

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

{sonilo_cli-0.8.2 → sonilo_cli-0.10.0}/src/sonilo_cli/__main__.py

@@ -167,6 +167,30 @@ def parse_segments(
     return value
 
 
+def _ducking(args: argparse.Namespace) -> Optional[bool]:
+    """Resolve --ducking / --no-ducking, or None to let the server default win.
+
+    `ducking` used to be default-ON server-side, so the only direction worth
+    expressing was turning it off and --no-ducking was the only flag. It is now
+    default-OFF, which makes --ducking the useful one. --no-ducking is kept
+    because dropping it would turn every script that passes it into a hard
+    argparse error; it now sends the explicit False the server would have
+    applied anyway.
+
+    Passing both is a contradiction with no sensible winner, so it exits rather
+    than silently picking one.
+    """
+    on = getattr(args, "ducking", False)
+    off = getattr(args, "no_ducking", False)
+    if on and off:
+        raise SystemExit("pass at most one of --ducking or --no-ducking")
+    if on:
+        return True
+    if off:
+        return False
+    return None
+
+
 def _segments(args: argparse.Namespace) -> Optional[List[Dict[str, Any]]]:
     """parse_segments() for whichever subcommand is running."""
     return parse_segments(args.segments, args.segments_shape, args.command)
@@ -285,12 +309,15 @@ def cmd_video_to_music(client: Sonilo, args: argparse.Namespace) -> None:
             preserve_speech=args.preserve_speech or None,
             output_format=fmt if fmt != "m4a" else None,
             variants_num=args.variants,
+            prompt_influence=args.prompt_influence,
         )
         _save_music_variants(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.
         track = client.video_to_music.generate(
             video=args.video, video_url=args.video_url, prompt=args.prompt,
-            segments=segments,
+            segments=segments, prompt_influence=args.prompt_influence,
         )
         path = track.save(out)
         _wrote(path, len(track.audio))
@@ -345,7 +372,7 @@ def _run_sound(client: Sonilo, args: argparse.Namespace, resource: Any, default_
         sfx_prompt=args.sfx_prompt,
         segments=_segments(args),
         preserve_speech=True if args.preserve_speech else None,
-        ducking=False if args.no_ducking else None,
+        ducking=_ducking(args),
         variants_num=args.variants,
         **extra,
     )
@@ -403,15 +430,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. 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.
+        # same reasoning as --ducking on the sound commands. Both ducking and
+        # keep_original_sound are default-OFF server-side, 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,
+        ducking=_ducking(args),
         preserve_speech=True if args.preserve_speech else None,
         isolate_vocals=True if args.isolate_vocals else None,
         variants_num=args.variants,
+        prompt_influence=args.prompt_influence,
     )
 
 
@@ -520,6 +547,19 @@ def _add_segments(parser: argparse.ArgumentParser, shape: _SegmentShape) -> None
     parser.set_defaults(segments_shape=shape)
 
 
+def _add_prompt_influence(parser: argparse.ArgumentParser) -> None:
+    # Only the two music-from-video commands take this — the API accepts it
+    # nowhere else. type=float so 0 arrives as 0.0, a real value ("let the
+    # video lead entirely"), distinct from the unset None that keeps the
+    # field off the wire and leaves the API its own 0.5 default.
+    parser.add_argument(
+        "--prompt-influence", dest="prompt_influence", type=float, default=None,
+        help="How strongly the generated music follows the prompt, 0-1 "
+             "(API default 0.5). Lower values let the video lead; higher "
+             "values follow the prompt more literally. Free of charge.",
+    )
+
+
 def _add_variants(parser: argparse.ArgumentParser) -> None:
     parser.add_argument(
         "--variants", type=int, default=None,
@@ -578,6 +618,7 @@ def build_parser() -> argparse.ArgumentParser:
     p_v2m.add_argument("--async", dest="use_async", action="store_true",
                        help="Submit and poll instead of streaming.")
     _add_variants(p_v2m)
+    _add_prompt_influence(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")
@@ -611,8 +652,14 @@ def build_parser() -> argparse.ArgumentParser:
     _add_segments(p_v2sd, SFX_SHAPE)
     p_v2sd.add_argument("--preserve-speech", dest="preserve_speech", action="store_true",
                         help="Keep source speech in the mix.")
+    p_v2sd.add_argument("--ducking", dest="ducking", action="store_true",
+                        help="Bring the source video's own speech into the mix and duck "
+                             "the generated bed under it. Off by default, so by default "
+                             "the result is the generated music and effects alone and "
+                             "there is no music_processed stem.")
     p_v2sd.add_argument("--no-ducking", dest="no_ducking", action="store_true",
-                        help="Disable automatic ducking (on by default server-side).")
+                        help="Explicit opt-out. Same as the default; kept so existing "
+                             "scripts keep working.")
     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.")
@@ -631,10 +678,13 @@ def build_parser() -> argparse.ArgumentParser:
                              "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("--ducking", dest="ducking", action="store_true",
+                        help="Duck the music under the voice instead of mixing it in at "
+                             "a static level. No effect without --keep-original-sound "
+                             "or --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.")
+                        help="Explicit opt-out. Same as the default; kept so existing "
+                             "scripts keep working.")
     p_v2vm.add_argument("--preserve-speech", dest="preserve_speech", action="store_true",
                         help="Keep only the source's isolated speech in the mix.")
     # Same aliasing as video-to-music, and here the endpoint collapses the two
@@ -645,6 +695,7 @@ def build_parser() -> argparse.ArgumentParser:
                         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)
+    _add_prompt_influence(p_v2vm)
     p_v2vm.set_defaults(func=cmd_video_to_video_music)
 
     p_v2vfx = sub.add_parser(
@@ -676,10 +727,13 @@ def build_parser() -> argparse.ArgumentParser:
                               "--preserve-speech. This command only.")
     p_v2vsd.add_argument("--preserve-speech", dest="preserve_speech", action="store_true",
                          help="Keep only the source's isolated speech in the mix.")
-    p_v2vsd.add_argument("--no-ducking", dest="no_ducking", action="store_true",
-                         help="Combine the voice and the generated bed as a static mix "
-                              "instead of a dynamic duck. No effect without "
+    p_v2vsd.add_argument("--ducking", dest="ducking", action="store_true",
+                         help="Duck the generated bed under the voice instead of mixing "
+                              "it in at a static level. No effect without "
                               "--keep-original-sound or --preserve-speech.")
+    p_v2vsd.add_argument("--no-ducking", dest="no_ducking", action="store_true",
+                         help="Explicit opt-out. Same as the default; kept so existing "
+                              "scripts keep working.")
     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.")

{sonilo_cli-0.8.2 → sonilo_cli-0.10.0}/tests/test_cli.py

@@ -369,15 +369,25 @@ def test_video_to_sound_ducking_absent_omits_field(tmp_path):
     )
     run(["video-to-sound", "--video-url", "http://x/y.mp4",
          "--output", str(tmp_path / "s.wav")])
-    # ducking is default-ON server-side: an unset --no-ducking must forward
-    # `None`, not `False`, so the field must be entirely absent from the
-    # form-encoded body (per build_v2s_parts).
+    # ducking is default-OFF server-side, and neither flag was passed, so the
+    # CLI must forward `None`, not `False` — the field has to be absent from
+    # the form-encoded body (per build_v2s_parts) and let the server decide.
     body = route.calls.last.request.content.decode()
     assert "ducking=" not in body
 
 
 @respx.mock
-def test_video_to_sound_no_ducking_sets_false(tmp_path):
+@pytest.mark.parametrize(
+    "flag, wire",
+    [
+        # --ducking is the direction that does something now that the server
+        # default is off; --no-ducking predates the flip, still parses so
+        # existing scripts do not break, and states the default explicitly.
+        ("--ducking", "ducking=true"),
+        ("--no-ducking", "ducking=false"),
+    ],
+)
+def test_video_to_sound_ducking_flags(tmp_path, flag, wire):
     route = respx.post(f"{BASE}/v1/video-to-sound").mock(
         return_value=httpx.Response(200, json={"task_id": "sd4", "status": "processing"})
     )
@@ -388,9 +398,15 @@ def test_video_to_sound_no_ducking_sets_false(tmp_path):
         return_value=httpx.Response(200, content=b"MIXED")
     )
     run(["video-to-sound", "--video-url", "http://x/y.mp4",
-         "--output", str(tmp_path / "s.wav"), "--no-ducking"])
+         "--output", str(tmp_path / "s.wav"), flag])
     body = route.calls.last.request.content.decode()
-    assert "ducking=false" in body
+    assert wire in body
+
+
+def test_video_to_sound_rejects_both_ducking_flags(tmp_path):
+    with pytest.raises(SystemExit):
+        run(["video-to-sound", "--video-url", "http://x/y.mp4",
+             "--output", str(tmp_path / "s.wav"), "--ducking", "--no-ducking"])
 
 
 @respx.mock
@@ -1080,3 +1096,64 @@ def test_video_to_video_commands_are_listed_in_top_level_help(command, capsys):
     with pytest.raises(SystemExit):
         main(["--help"])
     assert command in capsys.readouterr().out
+
+
+# --- --prompt-influence -------------------------------------------------------
+#
+# Only video-to-music and video-to-video-music offer the flag — the API
+# accepts prompt_influence nowhere else. Unset forwards None (field absent,
+# API default 0.5 stands); 0 is a real value and must be sent as 0.0.
+
+
+@respx.mock
+def test_video_to_music_prompt_influence_rides_the_streaming_path(tmp_path):
+    """prompt_influence is a generation parameter, valid on stream and async
+    alike, so unlike --format wav it must NOT force the async path."""
+    route = respx.post(f"{BASE}/v1/video-to-music").mock(
+        return_value=httpx.Response(200, text=_music_stream_body())
+    )
+    run(["video-to-music", "--video-url", "http://x/y.mp4",
+         "--prompt-influence", "0.8", "--output", str(tmp_path / "song.m4a")])
+    body = route.calls.last.request.content.decode()
+    assert "prompt_influence=0.8" in body
+
+
+@respx.mock
+def test_video_to_music_prompt_influence_zero_is_sent(tmp_path):
+    """0 means "let the video lead entirely" — a real request, distinct from
+    unset, so it goes on the wire (as 0.0: argparse's float parse)."""
+    route = respx.post(f"{BASE}/v1/video-to-music").mock(
+        return_value=httpx.Response(200, text=_music_stream_body())
+    )
+    run(["video-to-music", "--video-url", "http://x/y.mp4",
+         "--prompt-influence", "0", "--output", str(tmp_path / "song.m4a")])
+    body = route.calls.last.request.content.decode()
+    assert "prompt_influence=0.0" in body
+
+
+@respx.mock
+def test_video_to_music_omits_prompt_influence_when_unset(tmp_path):
+    route = respx.post(f"{BASE}/v1/video-to-music").mock(
+        return_value=httpx.Response(200, text=_music_stream_body())
+    )
+    run(["video-to-music", "--video-url", "http://x/y.mp4",
+         "--output", str(tmp_path / "song.m4a")])
+    # Absent, not "None" and not an explicit 0.5 pinning the API's default.
+    assert b"prompt_influence" not in route.calls.last.request.content
+
+
+@respx.mock
+def test_video_to_video_music_prompt_influence_reaches_the_request_body(tmp_path):
+    route = _mock_video_task("video-to-video-music", "vmpi1", "video_to_video_music")
+    run(["video-to-video-music", "--video-url", "http://x/y.mp4",
+         "--prompt-influence", "0.3", "--output", str(tmp_path / "s.mp4")])
+    body = route.calls.last.request.content.decode()
+    assert "prompt_influence=0.3" in body
+
+
+@respx.mock
+def test_video_to_video_music_omits_prompt_influence_when_unset(tmp_path):
+    route = _mock_video_task("video-to-video-music", "vmpi2", "video_to_video_music")
+    run(["video-to-video-music", "--video-url", "http://x/y.mp4",
+         "--output", str(tmp_path / "s.mp4")])
+    assert b"prompt_influence" not in route.calls.last.request.content