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

{sonilo_cli-0.11.0 → sonilo_cli-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sonilo-cli
-Version: 0.11.0
+Version: 0.13.0
 Summary: Command-line interface for the Sonilo API: generate music and sound effects from text or video
 Project-URL: Repository, https://github.com/sonilo-ai/sonilo-python
 Author: Sonilo AI
@@ -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.13,>=0.12.0
+Requires-Dist: sonilo<0.15,>=0.14.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: respx>=0.21; extra == 'dev'
@@ -95,6 +95,11 @@ 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 video-analysis --video clip.mp4 --variants 2
+    # prints a creative brief as JSON; generates nothing
     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 +225,41 @@ 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.
+
+### Video analysis
+
+`video-analysis` analyzes a video and prints a **creative brief** for scoring it. It is the one
+command that produces no media file — nothing is generated:
+
+    sonilo video-analysis --video clip.mp4 --prompt "focus on the chase" --variants 2
+
+- The brief goes to **stdout as JSON** so it can be piped into another tool: `segments` (a
+  time-aligned section plan) and `variations` (one ready-to-use generation prompt each). Pass
+  `--output brief.json` to write it to a file instead.
+- `--variants` is 1-5 (default 1) and is **billed per brief**.
+- Source videos may be at most 600 seconds long, and billing has a 10-second floor.
+- Feed a variation's prompt straight into the next command:
+
+      sonilo video-analysis --video clip.mp4 --output brief.json
+      sonilo video-to-music --video clip.mp4 --prompt "$(jq -r '.variations[0].prompt' brief.json)"
+
 ### Dubbing
 
 `dubbing` dubs a video into one or more target languages in a single async call:
@@ -246,7 +286,7 @@ required:
 
 | Free runs | Endpoints |
 | --- | --- |
-| 2 each | text-to-music, text-to-sfx, audio-ducking |
+| 2 each | text-to-music, text-to-sfx, audio-ducking, video-analysis |
 | 1 each | video-to-music, video-to-sfx, video-to-video-music, video-to-video-sfx, video-to-sound, video-to-video-sound |
 | 0 | dubbing |
 

{sonilo_cli-0.11.0 → sonilo_cli-0.13.0}/README.md

@@ -79,6 +79,11 @@ 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 video-analysis --video clip.mp4 --variants 2
+    # prints a creative brief as JSON; generates nothing
     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 +209,41 @@ 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.
+
+### Video analysis
+
+`video-analysis` analyzes a video and prints a **creative brief** for scoring it. It is the one
+command that produces no media file — nothing is generated:
+
+    sonilo video-analysis --video clip.mp4 --prompt "focus on the chase" --variants 2
+
+- The brief goes to **stdout as JSON** so it can be piped into another tool: `segments` (a
+  time-aligned section plan) and `variations` (one ready-to-use generation prompt each). Pass
+  `--output brief.json` to write it to a file instead.
+- `--variants` is 1-5 (default 1) and is **billed per brief**.
+- Source videos may be at most 600 seconds long, and billing has a 10-second floor.
+- Feed a variation's prompt straight into the next command:
+
+      sonilo video-analysis --video clip.mp4 --output brief.json
+      sonilo video-to-music --video clip.mp4 --prompt "$(jq -r '.variations[0].prompt' brief.json)"
+
 ### Dubbing
 
 `dubbing` dubs a video into one or more target languages in a single async call:
@@ -230,7 +270,7 @@ required:
 
 | Free runs | Endpoints |
 | --- | --- |
-| 2 each | text-to-music, text-to-sfx, audio-ducking |
+| 2 each | text-to-music, text-to-sfx, audio-ducking, video-analysis |
 | 1 each | video-to-music, video-to-sfx, video-to-video-music, video-to-video-sfx, video-to-sound, video-to-video-sound |
 | 0 | dubbing |
 

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

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

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

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

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

@@ -474,6 +474,87 @@ 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)
+
+
+def _analysis_payload(result: Any) -> dict:
+    """Flatten a VideoAnalysisResult back into the API's own envelope shape.
+
+    Deliberately re-emits the wire format rather than dumping the dataclass:
+    this output is meant to be piped into another tool (or read by an agent),
+    and it should look identical to what GET /v1/tasks returned. None-valued
+    accounting fields are dropped so a brief stays readable.
+    """
+    payload: dict = {
+        "task_id": result.task_id,
+        "status": result.status,
+        "segments": [
+            {"start": s.start, "end": s.end, "label": s.label, "prompt": s.prompt}
+            for s in result.segments
+        ],
+        "variations": [{"prompt": v.prompt} for v in result.variations],
+    }
+    for key in ("variants_num", "duration_seconds", "cost"):
+        value = getattr(result, key, None)
+        if value is not None:
+            payload[key] = value
+    return payload
+
+
+def cmd_video_analysis(client: Sonilo, args: argparse.Namespace) -> None:
+    """video-analysis is the one command that produces no media file. The
+    brief goes to stdout so it can be piped straight into the next tool;
+    --output is the opt-in for keeping a copy on disk."""
+    result = client.video_analysis.analyze(
+        video=args.video, video_url=args.video_url,
+        prompt=args.prompt, variants_num=args.variants,
+        timeout=args.timeout,
+    )
+    if not result.variations:
+        _fail("task succeeded but returned no creative brief")
+    payload = _analysis_payload(result)
+    if args.output is None:
+        _print_json(payload)
+        return
+    path = Path(args.output)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2) + "\n")
+    _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 +871,64 @@ 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_va = sub.add_parser(
+        "video-analysis",
+        help="Analyze a video and print a creative brief for scoring it",
+    )
+    _add_global(p_va)
+    _add_video_source(p_va)
+    p_va.add_argument(
+        "--prompt", default=None,
+        help="Optional guidance for the analysis, e.g. 'focus on the chase'.",
+    )
+    p_va.add_argument(
+        "--variants", type=int, default=None,
+        help="How many independent briefs to author for the same video (1-5). "
+             "Billed per brief. Default: 1",
+    )
+    p_va.add_argument(
+        "--output", default=None,
+        help="Write the brief to this .json file instead of printing it to stdout.",
+    )
+    p_va.add_argument(
+        "--timeout", type=float, default=600.0,
+        help="Give up waiting after this many seconds. Default: 600. A timed-out "
+             "task may still finish — resume it with `sonilo tasks get <task-id>`.",
+    )
+    p_va.set_defaults(func=cmd_video_analysis)
+
     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.13.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
@@ -1262,3 +1346,92 @@ def test_empty_env_var_falls_through_to_the_credential(monkeypatch):
     )
     main(["account"])
     assert route.calls.last.request.headers["authorization"] == "Bearer sk-stored"
+
+
+ANALYSIS_ACK = {"task_id": "va1", "status": "processing"}
+ANALYSIS_BODY = {
+    "task_id": "va1",
+    "type": "video_analysis",
+    "status": "succeeded",
+    "variants_num": 2,
+    "segments": [
+        {"start": 0, "end": 12, "label": "intro", "prompt": "sparse piano"},
+    ],
+    "variations": [
+        {"prompt": "cinematic strings, 90bpm"},
+        {"prompt": "lo-fi hip hop, warm keys"},
+    ],
+    "duration_seconds": 30.0,
+    "cost": 0.24,
+}
+
+
+def _mock_analysis():
+    respx.post(f"{BASE}/v1/video-analysis").mock(
+        return_value=httpx.Response(202, json=ANALYSIS_ACK)
+    )
+    respx.get(f"{BASE}/v1/tasks/va1").mock(
+        return_value=httpx.Response(200, json=ANALYSIS_BODY)
+    )
+
+
+@respx.mock
+def test_video_analysis_prints_the_brief_as_json(capsys):
+    """The result is a brief, not a file: it goes to stdout so it can be
+    piped, and nothing is written to disk unless --output says so."""
+    _mock_analysis()
+    run(["video-analysis", "--video-url", "https://x/v.mp4"])
+    out = json.loads(capsys.readouterr().out)
+    assert out["task_id"] == "va1"
+    assert out["segments"] == [
+        {"start": 0, "end": 12, "label": "intro", "prompt": "sparse piano"}
+    ]
+    assert [v["prompt"] for v in out["variations"]] == [
+        "cinematic strings, 90bpm",
+        "lo-fi hip hop, warm keys",
+    ]
+
+
+@respx.mock
+def test_video_analysis_sends_prompt_and_variants():
+    _mock_analysis()
+    route = respx.routes[0]
+    run([
+        "video-analysis",
+        "--video-url", "https://x/v.mp4",
+        "--prompt", "focus on the chase",
+        "--variants", "2",
+    ])
+    body = unquote_plus(route.calls.last.request.content.decode())
+    assert "prompt=focus on the chase" in body
+    assert "variants_num=2" in body
+
+
+@respx.mock
+def test_video_analysis_omits_unset_optionals():
+    _mock_analysis()
+    route = respx.routes[0]
+    run(["video-analysis", "--video-url", "https://x/v.mp4"])
+    body = unquote_plus(route.calls.last.request.content.decode())
+    assert "prompt" not in body
+    assert "variants_num" not in body
+
+
+@respx.mock
+def test_video_analysis_output_writes_the_brief_to_a_file(tmp_path, capsys):
+    _mock_analysis()
+    out = tmp_path / "brief.json"
+    run(["video-analysis", "--video-url", "https://x/v.mp4", "--output", str(out)])
+    written = json.loads(out.read_text())
+    assert written["variations"][0]["prompt"] == "cinematic strings, 90bpm"
+    # With --output the brief goes to the file, not to stdout.
+    assert "Wrote" in capsys.readouterr().out
+
+
+def test_video_analysis_requires_a_video_source(capsys):
+    with pytest.raises(SystemExit) as exc:
+        main(["--api-key", "sk-test", "video-analysis"])
+    assert exc.value.code == 1
+    # Asserted on the message, not just the exit code: an unknown command
+    # also exits 1, so the code alone would pass before the command exists.
+    assert "--video" in capsys.readouterr().err