sonilo-cli 0.15.0__tar.gz → 0.16.0__tar.gz

sonilo_cli-0.15.0/README.md → sonilo_cli-0.16.0/PKG-INFO

@@ -1,3 +1,19 @@
+Metadata-Version: 2.5
+Name: sonilo-cli
+Version: 0.16.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.18,>=0.17.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.
@@ -284,6 +300,20 @@ command that produces no media file — nothing is generated:
   original picture matters more than matching lip movement.
 - `--output` is a filename template, not a single destination: a dubbing task returns one video
   per language, so `--output clip.mp4` writes `clip.es.mp4`, `clip.fr.mp4`, etc.
+- `--ducking` ducks the background music/effects bed under the dubbed voice while it speaks;
+  off by default, so the bed otherwise stays at a static level. `--no-ducking` states that
+  default explicitly.
+- `--subtitle <language>=<path-or-url>` gives one language the script to speak, as an `.srt`/`.vtt`
+  file or an https URL. Repeat it once per language; the set must match `--languages` exactly.
+  The scripts are in the **target** language, not the source's:
+
+      sonilo dubbing --video clip.mp4 --languages es,fr \
+        --subtitle es=spanish.srt --subtitle fr=https://example.com/french.vtt --export-srt
+
+- `--export-srt` (requires `--subtitle`) returns a re-timed `.srt` per language, aligned to the
+  delivered audio with your lines kept verbatim. Each one is written beside its video
+  (`clip.es.mp4` -> `clip.es.srt`), and one status line per language is printed. A language whose
+  export is blocked still gets its video — only the `.srt` is missing.
 - Billing is per language, and dubbing has **no free trial runs** — see [Free trial](#free-trial)
   below.
 - `--timeout` defaults to 7200 seconds, matching the backend's own ceiling for a dubbing job

sonilo_cli-0.15.0/PKG-INFO → sonilo_cli-0.16.0/README.md

@@ -1,19 +1,3 @@
-Metadata-Version: 2.5
-Name: sonilo-cli
-Version: 0.15.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.17,>=0.16.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.
@@ -300,6 +284,20 @@ command that produces no media file — nothing is generated:
   original picture matters more than matching lip movement.
 - `--output` is a filename template, not a single destination: a dubbing task returns one video
   per language, so `--output clip.mp4` writes `clip.es.mp4`, `clip.fr.mp4`, etc.
+- `--ducking` ducks the background music/effects bed under the dubbed voice while it speaks;
+  off by default, so the bed otherwise stays at a static level. `--no-ducking` states that
+  default explicitly.
+- `--subtitle <language>=<path-or-url>` gives one language the script to speak, as an `.srt`/`.vtt`
+  file or an https URL. Repeat it once per language; the set must match `--languages` exactly.
+  The scripts are in the **target** language, not the source's:
+
+      sonilo dubbing --video clip.mp4 --languages es,fr \
+        --subtitle es=spanish.srt --subtitle fr=https://example.com/french.vtt --export-srt
+
+- `--export-srt` (requires `--subtitle`) returns a re-timed `.srt` per language, aligned to the
+  delivered audio with your lines kept verbatim. Each one is written beside its video
+  (`clip.es.mp4` -> `clip.es.srt`), and one status line per language is printed. A language whose
+  export is blocked still gets its video — only the `.srt` is missing.
 - Billing is per language, and dubbing has **no free trial runs** — see [Free trial](#free-trial)
   below.
 - `--timeout` defaults to 7200 seconds, matching the backend's own ceiling for a dubbing job

{sonilo_cli-0.15.0 → sonilo_cli-0.16.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sonilo-cli"
-version = "0.15.0"
+version = "0.16.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.16.0,<0.17"]
+dependencies = ["sonilo>=0.17.0,<0.18"]
 keywords = ["sonilo", "cli", "music", "sfx", "text-to-music", "video-to-music", "ai"]
 
 [project.urls]

{sonilo_cli-0.15.0 → sonilo_cli-0.16.0}/src/sonilo_cli/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "0.14.3"
+__version__ = "0.16.0"
 
 __all__ = ["__version__"]

{sonilo_cli-0.15.0 → sonilo_cli-0.16.0}/src/sonilo_cli/__main__.py

@@ -624,6 +624,44 @@ def _language_path(out: str, language: str) -> str:
     return str(base.with_name(f"{base.stem}.{language}{base.suffix or '.mp4'}"))
 
 
+def _subtitles(values: Optional[List[str]]) -> Optional[Dict[str, str]]:
+    """Turn repeated `--subtitle <lang>=<path-or-url>` values into the map the
+    SDK takes. The `=` is split once only, so a Windows path or a URL with its
+    own `=` survives. Neither the codes nor the language set are checked here —
+    the server owns both rules and names what it refused."""
+    if not values:
+        return None
+    subtitles: Dict[str, str] = {}
+    for value in values:
+        language, _, source = value.partition("=")
+        language = language.strip()
+        if not language or not source:
+            _fail(
+                f"--subtitle needs <language>=<path-or-url>, got {value!r} "
+                "(e.g. --subtitle es=spanish.srt)"
+            )
+        if language in subtitles:
+            _fail(f"--subtitle {language} given twice; one script per language")
+        subtitles[language] = source
+    return subtitles
+
+
+def _export_line(language: str, report: Dict[str, Any]) -> str:
+    """One status line per language. `alignment_loss` arrives as a float or as
+    a string — the pipeline stores numbers as strings — so it is formatted
+    through float() and simply omitted when it is neither."""
+    status = report.get("status") or "unknown"
+    line = f"Subtitle {language}: {status}"
+    try:
+        line += f" (alignment loss {float(report['alignment_loss']):.3f})"
+    except (KeyError, TypeError, ValueError):
+        pass
+    error = report.get("error")
+    if error:
+        line += f" — {error}"
+    return line
+
+
 def cmd_dubbing(client: Sonilo, args: argparse.Namespace) -> None:
     out = args.output if args.output is not None else "output.mp4"
     languages = None
@@ -631,13 +669,29 @@ def cmd_dubbing(client: Sonilo, args: argparse.Namespace) -> None:
         languages = [code.strip() for code in args.languages.split(",") if code.strip()]
         if not languages:
             _fail("--languages needs at least one language code, e.g. --languages es,fr")
+    subtitles = _subtitles(args.subtitle)
+    if args.export_srt and subtitles is None:
+        _fail("--export-srt needs --subtitle <language>=<path-or-url> for each language")
+    # Both files are derived from the same template, and the subtitle is
+    # written second: an .srt template would have clip.es.srt overwrite the
+    # video that had just been saved to clip.es.srt, reporting both writes as
+    # successes. Refuse it here rather than destroy the deliverable.
+    if args.export_srt and Path(out).suffix.lower() == ".srt":
+        _fail(
+            f"--output {out} ends in .srt, which --export-srt would overwrite with "
+            "the subtitle — name the video (e.g. --output clip.mp4) and the .srt "
+            "is written beside it"
+        )
     result = client.dubbing.generate(
         video=args.video,
         video_url=args.video_url,
         languages=languages,
+        ducking=_ducking(args),
         # Only sent when the flag is present, so the server keeps owning the
         # default (lip sync on).
         lipsync=False if args.no_lipsync else None,
+        subtitles=subtitles,
+        export_srt=True if args.export_srt else None,
         timeout=args.timeout,
     )
     if not result.outputs:
@@ -645,6 +699,17 @@ def cmd_dubbing(client: Sonilo, args: argparse.Namespace) -> None:
     for language in sorted(result.outputs):
         path = result.save(language, _language_path(out, language))
         _wrote(path, path.stat().st_size)
+    if not args.export_srt:
+        return
+    # The .srt lands beside its video (clip.es.mp4 -> clip.es.srt). A blocked
+    # export still delivers the video, so every requested language gets a
+    # status line whether or not a file came back with it.
+    for language in sorted(result.subtitle_export or result.subtitles):
+        if language in result.subtitles:
+            srt = Path(_language_path(out, language)).with_suffix(".srt")
+            path = result.save_subtitle(language, srt)
+            _wrote(path, path.stat().st_size)
+        print(_export_line(language, result.subtitle_export.get(language, {})))
 
 
 def _identity(body: Any) -> Any:
@@ -1023,6 +1088,29 @@ def build_parser() -> argparse.ArgumentParser:
              "or when preserving the exact original picture matters more than "
              "matching lip movement.",
     )
+    p_dub.add_argument(
+        "--ducking", dest="ducking", action="store_true",
+        help="Duck the background music/effects bed under the dubbed voice while "
+             "it speaks, instead of keeping it at a static level. Off by default.",
+    )
+    p_dub.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_dub.add_argument(
+        "--subtitle", dest="subtitle", action="append", default=None,
+        metavar="LANG=SOURCE",
+        help="Script to speak in one target language, as <language>=<path> or "
+             "<language>=<https URL>. Repeat once per language. Scripts are "
+             ".srt or .vtt in the TARGET language, not source transcripts.",
+    )
+    p_dub.add_argument(
+        "--export-srt", dest="export_srt", action="store_true",
+        help="Return a re-timed .srt per language, aligned to the delivered "
+             "audio and keeping your lines verbatim. Written beside each video "
+             "(clip.es.mp4 -> clip.es.srt). Requires --subtitle.",
+    )
     p_dub.add_argument(
         "--output", default=None,
         help="Filename template; one file is written per language with the code "

{sonilo_cli-0.15.0 → sonilo_cli-0.16.0}/tests/test_cli.py

@@ -720,6 +720,249 @@ def test_dubbing_without_languages_omits_the_field(tmp_path):
     assert b"languages" not in route.calls.last.request.content
 
 
+# --- dubbing ducking -------------------------------------------------------
+
+
+def _stub_plain_dubbing():
+    route = respx.post(f"{BASE}/v1/dubbing").mock(
+        return_value=httpx.Response(202, json={"task_id": "db1", "status": "processing"})
+    )
+    respx.get(f"{BASE}/v1/tasks/db1").mock(
+        return_value=httpx.Response(200, json={
+            "task_id": "db1", "status": "succeeded",
+            "outputs": {"es": "https://r2/es.mp4"},
+        })
+    )
+    respx.get("https://r2/es.mp4").mock(
+        return_value=httpx.Response(200, content=b"es-bytes")
+    )
+    return route
+
+
+@respx.mock
+@pytest.mark.parametrize(
+    "flags, wire",
+    [
+        # ducking is default-OFF server-side, so each flag is only ever sent
+        # to change that default.
+        (["--ducking"], "ducking=true"),
+        (["--no-ducking"], "ducking=false"),
+    ],
+)
+def test_dubbing_ducking_flags(tmp_path, flags, wire):
+    route = _stub_plain_dubbing()
+    run([
+        "dubbing", "--video-url", "https://x/v.mp4",
+        "--output", str(tmp_path / "clip.mp4"),
+    ] + flags)
+    assert wire in unquote_plus(route.calls.last.request.content.decode())
+
+
+@respx.mock
+def test_dubbing_omits_ducking_when_unset(tmp_path):
+    route = _stub_plain_dubbing()
+    run([
+        "dubbing", "--video-url", "https://x/v.mp4",
+        "--output", str(tmp_path / "clip.mp4"),
+    ])
+    # Absent must stay absent: the server default (ducking off) only applies
+    # when the field is not sent at all.
+    assert "ducking=" not in route.calls.last.request.content.decode()
+
+
+def test_dubbing_rejects_both_ducking_flags(tmp_path):
+    with pytest.raises(SystemExit) as exc:
+        run(["dubbing", "--video-url", "https://x/v.mp4",
+             "--output", str(tmp_path / "clip.mp4"), "--ducking", "--no-ducking"])
+    # The helper's own message, not argparse's: matching only the exit would
+    # also pass against a build with neither flag defined.
+    assert "pass at most one of --ducking or --no-ducking" in str(exc.value)
+
+
+# --- dubbing subtitles ----------------------------------------------------
+
+SUBTITLED_BODY = {
+    "task_id": "db1",
+    "type": "dubbing",
+    "status": "succeeded",
+    "outputs": {"es": "https://r2/es.mp4", "fr": "https://r2/fr.mp4"},
+    # fr's export was blocked: its video is still delivered, with no .srt.
+    "subtitles": {"es": "https://r2/es.srt"},
+    "subtitle_export": {
+        # The pipeline stores numbers as strings, so the loss arrives as one.
+        "es": {"status": "exported", "alignment_loss": "0.6305176995017312"},
+        "fr": {"status": "blocked", "error": "alignment failed"},
+    },
+}
+
+
+def _stub_subtitled_dubbing():
+    route = respx.post(f"{BASE}/v1/dubbing").mock(
+        return_value=httpx.Response(202, json={"task_id": "db1", "status": "processing"})
+    )
+    respx.get(f"{BASE}/v1/tasks/db1").mock(
+        return_value=httpx.Response(200, json=SUBTITLED_BODY)
+    )
+    for language in ("es", "fr"):
+        respx.get(f"https://r2/{language}.mp4").mock(
+            return_value=httpx.Response(200, content=f"{language}-bytes".encode())
+        )
+    respx.get("https://r2/es.srt").mock(
+        return_value=httpx.Response(200, content=b"1\nhola\n")
+    )
+    return route
+
+
+@respx.mock
+def test_dubbing_sends_subtitle_urls(tmp_path):
+    route = _stub_subtitled_dubbing()
+    run([
+        "dubbing",
+        "--video-url", "https://x/v.mp4",
+        "--languages", "es,fr",
+        "--subtitle", "es=https://x/es.srt",
+        "--subtitle", "fr=https://x/fr.vtt",
+        "--output", str(tmp_path / "clip.mp4"),
+    ])
+    body = unquote_plus(route.calls.last.request.content.decode())
+    assert "subtitles[es]=https://x/es.srt" in body
+    assert "subtitles[fr]=https://x/fr.vtt" in body
+
+
+@respx.mock
+def test_dubbing_uploads_local_subtitle_files(tmp_path):
+    route = _stub_subtitled_dubbing()
+    script = tmp_path / "spanish.srt"
+    script.write_text("1\n")
+    run([
+        "dubbing",
+        "--video-url", "https://x/v.mp4",
+        "--languages", "es,fr",
+        "--subtitle", f"es={script}",
+        "--subtitle", "fr=https://x/fr.vtt",
+        "--output", str(tmp_path / "clip.mp4"),
+    ])
+    body = route.calls.last.request.content.decode(errors="replace")
+    assert 'name="subtitles[es]"' in body
+    assert 'filename="spanish.srt"' in body
+
+
+@respx.mock
+def test_dubbing_export_srt_writes_the_srt_beside_each_video(tmp_path, capsys):
+    _stub_subtitled_dubbing()
+    run([
+        "dubbing",
+        "--video-url", "https://x/v.mp4",
+        "--languages", "es,fr",
+        "--subtitle", "es=https://x/es.srt",
+        "--subtitle", "fr=https://x/fr.vtt",
+        "--export-srt",
+        "--output", str(tmp_path / "clip.mp4"),
+    ])
+    assert (tmp_path / "clip.es.mp4").read_bytes() == b"es-bytes"
+    assert (tmp_path / "clip.es.srt").read_bytes() == b"1\nhola\n"
+    # fr's export was blocked, so there is a video but no .srt for it.
+    assert (tmp_path / "clip.fr.mp4").exists()
+    assert not (tmp_path / "clip.fr.srt").exists()
+    out = capsys.readouterr().out
+    assert "Subtitle es: exported (alignment loss 0.631)" in out
+    assert "Subtitle fr: blocked" in out
+
+
+@respx.mock
+def test_dubbing_export_srt_tolerates_a_numeric_alignment_loss(tmp_path, capsys):
+    respx.post(f"{BASE}/v1/dubbing").mock(
+        return_value=httpx.Response(202, json={"task_id": "db1", "status": "processing"})
+    )
+    respx.get(f"{BASE}/v1/tasks/db1").mock(
+        return_value=httpx.Response(200, json={
+            "task_id": "db1", "status": "succeeded",
+            "outputs": {"es": "https://r2/es.mp4"},
+            "subtitles": {"es": "https://r2/es.srt"},
+            "subtitle_export": {"es": {"status": "exported", "alignment_loss": 0.25}},
+        })
+    )
+    respx.get("https://r2/es.mp4").mock(
+        return_value=httpx.Response(200, content=b"es-bytes")
+    )
+    respx.get("https://r2/es.srt").mock(
+        return_value=httpx.Response(200, content=b"1\nhola\n")
+    )
+    run([
+        "dubbing",
+        "--video-url", "https://x/v.mp4",
+        "--subtitle", "es=https://x/es.srt",
+        "--export-srt",
+        "--output", str(tmp_path / "clip.mp4"),
+    ])
+    assert "Subtitle es: exported (alignment loss 0.250)" in capsys.readouterr().out
+
+
+def test_dubbing_export_srt_refuses_an_srt_output_template(capsys, tmp_path):
+    """Both files come from one template and the subtitle is written second, so
+    an .srt template would silently overwrite the dubbed video."""
+    with pytest.raises(SystemExit) as exc:
+        main([
+            "--api-key", "sk-test", "dubbing", "--video-url", "https://x/v.mp4",
+            "--subtitle", "es=https://x/es.srt", "--export-srt",
+            "--output", str(tmp_path / "clip.SRT"),
+        ])
+    assert exc.value.code == 1
+    err = capsys.readouterr().err
+    assert "--export-srt would overwrite" in err
+    assert not (tmp_path / "clip.es.SRT").exists()
+
+
+def test_dubbing_export_srt_without_a_subtitle_exits_1(capsys):
+    with pytest.raises(SystemExit) as exc:
+        main([
+            "--api-key", "sk-test", "dubbing",
+            "--video-url", "https://x/v.mp4", "--export-srt",
+        ])
+    assert exc.value.code == 1
+    assert "--subtitle" in capsys.readouterr().err
+
+
+def test_dubbing_rejects_a_subtitle_without_a_language(capsys):
+    with pytest.raises(SystemExit) as exc:
+        main([
+            "--api-key", "sk-test", "dubbing",
+            "--video-url", "https://x/v.mp4", "--subtitle", "spanish.srt",
+        ])
+    assert exc.value.code == 1
+    # Match our own message, not just the flag name: argparse's "unrecognized
+    # arguments" error quotes the flag too, so a laxer assertion would pass
+    # against a build where --subtitle does not exist at all.
+    err = capsys.readouterr().err
+    assert "--subtitle needs <language>=<path-or-url>" in err
+    assert "'spanish.srt'" in err
+
+
+def test_dubbing_rejects_the_same_language_twice(capsys):
+    with pytest.raises(SystemExit) as exc:
+        main([
+            "--api-key", "sk-test", "dubbing", "--video-url", "https://x/v.mp4",
+            "--subtitle", "es=a.srt", "--subtitle", "es=b.srt",
+        ])
+    assert exc.value.code == 1
+    assert "twice" in capsys.readouterr().err
+
+
+@respx.mock
+def test_dubbing_rejects_a_subtitle_that_is_not_srt_or_vtt(tmp_path, capsys):
+    route = respx.post(f"{BASE}/v1/dubbing")
+    script = tmp_path / "es.txt"
+    script.write_text("hola")
+    with pytest.raises(SystemExit) as exc:
+        main([
+            "--api-key", "sk-test", "dubbing",
+            "--video-url", "https://x/v.mp4", "--subtitle", f"es={script}",
+        ])
+    assert exc.value.code == 1
+    assert "'es.txt' must be .srt or .vtt" in capsys.readouterr().err
+    assert not route.called
+
+
 # --- --segments -----------------------------------------------------------
 #
 # The two shapes are not interchangeable: music segments are