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

sonilo_cli-0.11.0/README.md → sonilo_cli-0.12.0/PKG-INFO

@@ -1,3 +1,19 @@
+Metadata-Version: 2.5
+Name: sonilo-cli
+Version: 0.12.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.14,>=0.13.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.
@@ -79,6 +95,9 @@ production sign-in coexist without overwriting each other.
     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 audio-ducking --voice interview.mp4 --music-url https://example.com/bed.wav
+    # ducks the existing music bed under the voice; a video voice comes back
+    # as a new .mp4 with the ducked mix muxed in
     sonilo dubbing --video-url https://example.com/clip.mp4 --languages es,fr --output dubbed.mp4
     # writes dubbed.es.mp4 and dubbed.fr.mp4
     sonilo tasks get <task-id>
@@ -204,6 +223,24 @@ they differ only in what comes back: `video-to-sound` writes the mixed **audio**
   or ducking altered the music bed.
 - Both also take `--variants` — see [Variants](#variants) above.
 
+### Audio ducking
+
+`audio-ducking` mixes an **existing** music bed under an **existing** voice track — nothing is
+generated, so reach for it when the music is fixed or external. (When the music is being generated
+for the same clip anyway, `video-to-sound` or `video-to-music` duck internally as part of that one
+call instead.)
+
+    sonilo audio-ducking --voice interview.mp4 --music-url https://example.com/bed.wav
+
+- Exactly one of `--voice` / `--voice-url` and one of `--music` / `--music-url`; a local file and a
+  URL mix freely across the two inputs.
+- The **voice** may be audio or video: a video's own audio track becomes the voice, and the ducked
+  mix is muxed back into a new video, so the result is a `.mp4` instead of a `.wav`. The default
+  `--output` name follows what came back (`output.wav` or `output.mp4`).
+- The **music** must be audio (`wav, mp3, m4a, aac, ogg, flac`). The API does not detect a video
+  there, so the CLI rejects a local video file up front rather than let it be mishandled silently.
+- Each input is capped at 360 seconds server-side.
+
 ### Dubbing
 
 `dubbing` dubs a video into one or more target languages in a single async call:

sonilo_cli-0.11.0/PKG-INFO → sonilo_cli-0.12.0/README.md

@@ -1,19 +1,3 @@
-Metadata-Version: 2.5
-Name: sonilo-cli
-Version: 0.11.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.13,>=0.12.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.
@@ -95,6 +79,9 @@ production sign-in coexist without overwriting each other.
     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 audio-ducking --voice interview.mp4 --music-url https://example.com/bed.wav
+    # ducks the existing music bed under the voice; a video voice comes back
+    # as a new .mp4 with the ducked mix muxed in
     sonilo dubbing --video-url https://example.com/clip.mp4 --languages es,fr --output dubbed.mp4
     # writes dubbed.es.mp4 and dubbed.fr.mp4
     sonilo tasks get <task-id>
@@ -220,6 +207,24 @@ they differ only in what comes back: `video-to-sound` writes the mixed **audio**
   or ducking altered the music bed.
 - Both also take `--variants` — see [Variants](#variants) above.
 
+### Audio ducking
+
+`audio-ducking` mixes an **existing** music bed under an **existing** voice track — nothing is
+generated, so reach for it when the music is fixed or external. (When the music is being generated
+for the same clip anyway, `video-to-sound` or `video-to-music` duck internally as part of that one
+call instead.)
+
+    sonilo audio-ducking --voice interview.mp4 --music-url https://example.com/bed.wav
+
+- Exactly one of `--voice` / `--voice-url` and one of `--music` / `--music-url`; a local file and a
+  URL mix freely across the two inputs.
+- The **voice** may be audio or video: a video's own audio track becomes the voice, and the ducked
+  mix is muxed back into a new video, so the result is a `.mp4` instead of a `.wav`. The default
+  `--output` name follows what came back (`output.wav` or `output.mp4`).
+- The **music** must be audio (`wav, mp3, m4a, aac, ogg, flac`). The API does not detect a video
+  there, so the CLI rejects a local video file up front rather than let it be mishandled silently.
+- Each input is capped at 360 seconds server-side.
+
 ### Dubbing
 
 `dubbing` dubs a video into one or more target languages in a single async call:

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

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

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

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

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

@@ -474,6 +474,42 @@ def cmd_video_to_video_sfx(client: Sonilo, args: argparse.Namespace) -> None:
     )
 
 
+# The music-bed extensions audio-ducking accepts for a local --music file —
+# the MCP server's _AUDIO_EXTS, kept identical so the two surfaces accept and
+# reject the same files. A whitelist (not a video-extension blacklist) because
+# the failure it guards against is silent: the API never probes the music
+# input for a video stream, so a video sent there is mishandled without an
+# error. The voice input needs no such guard — it may legitimately be audio
+# or video, and the API probes it.
+_MUSIC_AUDIO_EXTS = (".wav", ".mp3", ".m4a", ".aac", ".ogg", ".flac")
+
+
+def cmd_audio_ducking(client: Sonilo, args: argparse.Namespace) -> None:
+    if args.music is not None and Path(args.music).suffix.lower() not in _MUSIC_AUDIO_EXTS:
+        _fail(
+            f"--music must be an audio file ({', '.join(_MUSIC_AUDIO_EXTS)}) — "
+            "the API does not detect a video here and would mishandle it. "
+            "The voice input is the one that may be a video."
+        )
+    result = client.audio_ducking.generate(
+        voice=args.voice,
+        voice_url=args.voice_url,
+        music=args.music,
+        music_url=args.music_url,
+    )
+    # Default output name follows what actually came back: a .wav, or a .mp4
+    # (ducked mix re-muxed in) when the voice input was a video. An explicit
+    # --output is used verbatim, same as the video-out commands.
+    out = args.output
+    if out is None:
+        ext = Path(urlparse(result.output_url or "").path).suffix
+        if not ext:
+            ext = ".mp4" if result.output_type == "video" else ".wav"
+        out = f"output{ext}"
+    path = result.save(out)
+    _wrote(path, path.stat().st_size)
+
+
 # Matched to the dubbing backend's own ceiling: it polls its pipeline for up
 # to 7200s (2 hours), so anything shorter abandons a job the user has already
 # been charged for. The SDK's generic DEFAULT_WAIT_TIMEOUT of 600s is far too
@@ -790,6 +826,38 @@ def build_parser() -> argparse.ArgumentParser:
     _add_variants(p_v2vsd)
     p_v2vsd.set_defaults(func=cmd_video_to_video_sound)
 
+    p_duck = sub.add_parser(
+        "audio-ducking", help="Duck an existing music bed under a voice track"
+    )
+    _add_global(p_duck)
+    voice_group = p_duck.add_mutually_exclusive_group(required=True)
+    voice_group.add_argument(
+        "--voice", default=None,
+        help="Local voice track. May be audio or video: a video's own audio "
+             "track becomes the voice, and the ducked mix is muxed back into "
+             "a new video.",
+    )
+    voice_group.add_argument(
+        "--voice-url", dest="voice_url", default=None,
+        help="Remote voice audio/video URL.",
+    )
+    music_group = p_duck.add_mutually_exclusive_group(required=True)
+    music_group.add_argument(
+        "--music", default=None,
+        help="Local music bed. Audio only (wav, mp3, m4a, aac, ogg, flac) — "
+             "the API does not detect a video here, so the CLI rejects one.",
+    )
+    music_group.add_argument(
+        "--music-url", dest="music_url", default=None,
+        help="Remote music audio URL.",
+    )
+    p_duck.add_argument(
+        "--output", default=None,
+        help="Where to save the result. Default: output.wav, or output.mp4 "
+             "when the voice input was a video.",
+    )
+    p_duck.set_defaults(func=cmd_audio_ducking)
+
     p_dub = sub.add_parser("dubbing", help="Dub a video into other languages")
     _add_global(p_dub)
     _add_video_source(p_dub)

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

@@ -523,6 +523,90 @@ def test_video_to_video_sound_requires_a_video_source():
     assert exc.value.code == 1
 
 
+# --- audio-ducking --------------------------------------------------------
+#
+# Same flat output_url envelope as video-to-sound, no stems. The result is a
+# .wav, or a .mp4 (ducked mix re-muxed in) when the voice input was a video.
+
+DUCKING_SUCCESS_BODY = {
+    "task_id": "ad1",
+    "type": "audio_ducking",
+    "status": "succeeded",
+    "output_url": "https://r2.example.com/ducked.wav",
+    "output_type": "audio",
+    "output_bytes": 5,
+}
+
+
+@respx.mock
+def test_audio_ducking_saves_output(tmp_path):
+    route = respx.post(f"{BASE}/v1/audio-ducking").mock(
+        return_value=httpx.Response(202, json={"task_id": "ad1", "status": "processing"})
+    )
+    respx.get(f"{BASE}/v1/tasks/ad1").mock(
+        return_value=httpx.Response(200, json=DUCKING_SUCCESS_BODY)
+    )
+    respx.get("https://r2.example.com/ducked.wav").mock(
+        return_value=httpx.Response(200, content=b"DUCKED")
+    )
+    out = tmp_path / "mix.wav"
+    run(["audio-ducking", "--voice-url", "https://x/v.wav",
+         "--music-url", "https://x/m.wav", "--output", str(out)])
+    assert route.called
+    content = route.calls[0].request.content
+    assert b"voice_url" in content and b"music_url" in content
+    assert out.read_bytes() == b"DUCKED"
+
+
+@respx.mock
+def test_audio_ducking_default_output_follows_result_type(tmp_path, monkeypatch):
+    # A video voice input comes back as an mp4; the default output name must
+    # follow the result, not assume audio.
+    monkeypatch.chdir(tmp_path)
+    respx.post(f"{BASE}/v1/audio-ducking").mock(
+        return_value=httpx.Response(202, json={"task_id": "ad2", "status": "processing"})
+    )
+    respx.get(f"{BASE}/v1/tasks/ad2").mock(
+        return_value=httpx.Response(200, json={
+            **DUCKING_SUCCESS_BODY, "task_id": "ad2",
+            "output_url": "https://r2.example.com/ducked.mp4",
+            "output_type": "video",
+        })
+    )
+    respx.get("https://r2.example.com/ducked.mp4").mock(
+        return_value=httpx.Response(200, content=b"MP4DATA")
+    )
+    run(["audio-ducking", "--voice-url", "https://x/v.mp4",
+         "--music-url", "https://x/m.wav"])
+    assert (tmp_path / "output.mp4").read_bytes() == b"MP4DATA"
+
+
+def test_audio_ducking_requires_a_voice_source():
+    with pytest.raises(SystemExit) as exc:
+        run(["audio-ducking", "--music-url", "https://x/m.wav"])
+    assert exc.value.code == 1
+
+
+def test_audio_ducking_requires_a_music_source():
+    with pytest.raises(SystemExit) as exc:
+        run(["audio-ducking", "--voice-url", "https://x/v.wav"])
+    assert exc.value.code == 1
+
+
+@respx.mock
+def test_audio_ducking_rejects_a_video_music_file(tmp_path, capsys):
+    # The API never probes the music input for a video stream, so a video
+    # there is mishandled silently — the CLI must refuse before any request.
+    music = tmp_path / "background.mp4"
+    music.write_bytes(b"m")
+    with pytest.raises(SystemExit) as exc:
+        run(["audio-ducking", "--voice-url", "https://x/v.wav",
+             "--music", str(music)])
+    assert exc.value.code == 1
+    assert "audio" in capsys.readouterr().err
+    assert not respx.calls
+
+
 def test_cli_identifies_itself_not_the_sdk():
     """CLI traffic must be separable from direct SDK use in analytics."""
     import sonilo_cli