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

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: sonilo-cli
-Version: 0.10.0
+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
@@ -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.14,>=0.13.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: respx>=0.21; extra == 'dev'
@@ -22,16 +22,67 @@ Command-line interface for the [Sonilo API](https://github.com/sonilo-ai/sonilo-
 
     pip install sonilo-cli
 
-## Auth
+## Signing in
 
-Set your API key once:
+Run this once per machine — there is no key to create, paste, or export:
+
+    sonilo login
+
+It prints a one-time code and opens your browser to platform.sonilo.com. Sign
+in, confirm the code matches what the terminal printed, and approve; the CLI is
+waiting on that page and continues by itself. Every command works from then on.
+
+Approving mints an ordinary Sonilo API key on your account, named
+`cli: <hostname>` and valid for **90 days**, stored in
+`~/.config/sonilo/credentials.json` (`$XDG_CONFIG_HOME/sonilo/` when that is
+set), owner-readable only. It is visible and revocable at
+[the dashboard](https://platform.sonilo.com/dashboard/api-keys) like any other
+key.
+
+    sonilo whoami    # which account, key prefix, expiry, and which source is active
+    sonilo logout    # revoke the key server-side, then forget it locally
+
+`logout` revokes before forgetting, so a machine that loses the file never
+leaves a live key behind. If the revoke cannot reach the API the credential is
+deliberately kept and you are pointed at the dashboard, rather than being left
+holding a key nothing can revoke.
+
+Signing in again while already signed in reports the existing session; use
+`--force` to replace it (that mints a fresh key and revokes the one it
+replaces). When a credential has expired you do not need the flag — `sonilo
+login` treats an expired sign-in as no sign-in. On a machine with no browser,
+add `--no-browser` and approve the printed URL from another device.
+
+The credential file is shared with the JS CLI (`npm install -g sonilo-cli`) and
+read by [sonilo-mcp](https://github.com/sonilo-ai/sonilo-mcp) 0.16.0+, so one
+sign-in covers all three — an MCP host config then needs no `env` block at all.
+
+## Auth with an API key
+
+Signing in is optional. A key from
+[the dashboard](https://platform.sonilo.com/dashboard/api-keys) works exactly as
+it always has, which is what you want for CI, containers, and anything
+non-interactive — there is no browser there to approve with, and a 90-day expiry
+is not something a pipeline should depend on:
 
     export SONILO_API_KEY=sk-...
 
 or pass `--api-key sk-...` on any command.
 
+Credentials resolve most-explicit-first: `--api-key`, then `SONILO_API_KEY`,
+then the stored sign-in. That order is a guarantee, not an accident — an
+exported `SONILO_API_KEY` keeps winning after you upgrade, so adding a `sonilo
+login` on the same machine cannot quietly move your calls to another account.
+
+Set `SONILO_API_URL` (or pass `--api-base` to `login`) to point at another
+environment. Credentials are stored per host, so a staging sign-in and a
+production sign-in coexist without overwriting each other.
+
 ## Commands
 
+    sonilo login                       # sign in with your browser, no key needed
+    sonilo whoami                      # show the active account and credential source
+    sonilo logout                      # revoke the stored key and forget it
     sonilo account                     # plan limits and available services
     sonilo usage --days 7              # usage summary
     sonilo text-to-music --prompt "warm lo-fi piano, rain" --duration 30
@@ -44,6 +95,9 @@ or pass `--api-key sk-...` on any command.
     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>
@@ -169,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.10.0 → sonilo_cli-0.12.0}/README.md

@@ -6,16 +6,67 @@ Command-line interface for the [Sonilo API](https://github.com/sonilo-ai/sonilo-
 
     pip install sonilo-cli
 
-## Auth
+## Signing in
 
-Set your API key once:
+Run this once per machine — there is no key to create, paste, or export:
+
+    sonilo login
+
+It prints a one-time code and opens your browser to platform.sonilo.com. Sign
+in, confirm the code matches what the terminal printed, and approve; the CLI is
+waiting on that page and continues by itself. Every command works from then on.
+
+Approving mints an ordinary Sonilo API key on your account, named
+`cli: <hostname>` and valid for **90 days**, stored in
+`~/.config/sonilo/credentials.json` (`$XDG_CONFIG_HOME/sonilo/` when that is
+set), owner-readable only. It is visible and revocable at
+[the dashboard](https://platform.sonilo.com/dashboard/api-keys) like any other
+key.
+
+    sonilo whoami    # which account, key prefix, expiry, and which source is active
+    sonilo logout    # revoke the key server-side, then forget it locally
+
+`logout` revokes before forgetting, so a machine that loses the file never
+leaves a live key behind. If the revoke cannot reach the API the credential is
+deliberately kept and you are pointed at the dashboard, rather than being left
+holding a key nothing can revoke.
+
+Signing in again while already signed in reports the existing session; use
+`--force` to replace it (that mints a fresh key and revokes the one it
+replaces). When a credential has expired you do not need the flag — `sonilo
+login` treats an expired sign-in as no sign-in. On a machine with no browser,
+add `--no-browser` and approve the printed URL from another device.
+
+The credential file is shared with the JS CLI (`npm install -g sonilo-cli`) and
+read by [sonilo-mcp](https://github.com/sonilo-ai/sonilo-mcp) 0.16.0+, so one
+sign-in covers all three — an MCP host config then needs no `env` block at all.
+
+## Auth with an API key
+
+Signing in is optional. A key from
+[the dashboard](https://platform.sonilo.com/dashboard/api-keys) works exactly as
+it always has, which is what you want for CI, containers, and anything
+non-interactive — there is no browser there to approve with, and a 90-day expiry
+is not something a pipeline should depend on:
 
     export SONILO_API_KEY=sk-...
 
 or pass `--api-key sk-...` on any command.
 
+Credentials resolve most-explicit-first: `--api-key`, then `SONILO_API_KEY`,
+then the stored sign-in. That order is a guarantee, not an accident — an
+exported `SONILO_API_KEY` keeps winning after you upgrade, so adding a `sonilo
+login` on the same machine cannot quietly move your calls to another account.
+
+Set `SONILO_API_URL` (or pass `--api-base` to `login`) to point at another
+environment. Credentials are stored per host, so a staging sign-in and a
+production sign-in coexist without overwriting each other.
+
 ## Commands
 
+    sonilo login                       # sign in with your browser, no key needed
+    sonilo whoami                      # show the active account and credential source
+    sonilo logout                      # revoke the stored key and forget it
     sonilo account                     # plan limits and available services
     sonilo usage --days 7              # usage summary
     sonilo text-to-music --prompt "warm lo-fi piano, rain" --duration 30
@@ -28,6 +79,9 @@ or pass `--api-key sk-...` on any command.
     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>
@@ -153,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.10.0 → sonilo_cli-0.12.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sonilo-cli"
-version = "0.10.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.10.0 → sonilo_cli-0.12.0}/src/sonilo_cli/__init__.py

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

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

@@ -12,7 +12,8 @@ from urllib.parse import urlparse
 from sonilo import Sonilo
 from sonilo.errors import APIError, SoniloError
 
-from sonilo_cli import __version__
+from sonilo_cli import __version__, credentials
+from sonilo_cli.login import LoginError, cmd_login, cmd_logout, cmd_whoami
 
 
 class _Parser(argparse.ArgumentParser):
@@ -196,12 +197,34 @@ def _segments(args: argparse.Namespace) -> Optional[List[Dict[str, Any]]]:
     return parse_segments(args.segments, args.segments_shape, args.command)
 
 
-def build_client(api_key: Optional[str]) -> Sonilo:
+def _expired(iso: str) -> bool:
+    """Whether a stored credential's expiry has passed.
+
+    Reuses login's parser so both paths agree on what "expired" means, and on
+    treating an unparseable timestamp as *not* expired — the API is the
+    authority on whether a key works, and refusing to run over a formatting
+    quirk would be worse than letting a dead key earn its own 401.
+    """
+    from sonilo_cli.login import _is_expired
+
+    return _is_expired(iso)
+
+
+def build_client(api_key: Optional[str], path: Optional[Path] = None) -> Sonilo:
+    api_base = os.environ.get("SONILO_API_URL", credentials.DEFAULT_API_BASE).rstrip("/")
+    # Order is a compatibility promise: an exported SONILO_API_KEY keeps winning
+    # over a stored credential, so upgrading never moves someone's account.
     key = api_key or os.environ.get("SONILO_API_KEY")
+    if not key:
+        stored = credentials.read_credential(api_base, path)
+        if stored is not None:
+            if _expired(stored.get("expires_at", "")):
+                _fail('your sonilo login expired — run "sonilo login" again')
+            key = stored["api_key"]
     if not key:
         _fail(
-            "no API key — pass --api-key <key> or set the "
-            "SONILO_API_KEY environment variable"
+            'no API key — run "sonilo login", or pass --api-key <key>, or set '
+            "the SONILO_API_KEY environment variable"
         )
     # Identify as the CLI rather than inheriting the SDK's own name, so CLI
     # traffic stays separable from direct SDK use in server-side analytics.
@@ -451,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
@@ -577,6 +636,33 @@ def build_parser() -> argparse.ArgumentParser:
     _add_global(parser)
     sub = parser.add_subparsers(dest="command", metavar="<command>")
 
+    # login/logout/whoami run *before* a client exists — build_client exits when
+    # no key is available, which is the exact situation login is for. The
+    # needs_client=False flag is what main() checks to skip that.
+    p_login = sub.add_parser("login", help="Sign in and store an API key for future commands")
+    _add_global(p_login)
+    p_login.add_argument("--force", action="store_true",
+                         help="Sign in again even if already signed in, replacing the stored key.")
+    p_login.add_argument("--no-browser", action="store_true", dest="no_browser",
+                         help="Print the URL instead of opening a browser.")
+    p_login.add_argument("--api-base", dest="api_base", default=None,
+                         help="Sign in against a non-default API base URL.")
+    p_login.set_defaults(func=lambda client, args: cmd_login(args), needs_client=False)
+
+    p_logout = sub.add_parser("logout", help="Revoke the stored key and forget it locally")
+    _add_global(p_logout)
+    p_logout.add_argument("--local-only", action="store_true", dest="local_only",
+                          help="Forget the credential without revoking the key server-side.")
+    p_logout.add_argument("--api-base", dest="api_base", default=None,
+                          help="Act on the credential for a non-default API base URL.")
+    p_logout.set_defaults(func=lambda client, args: cmd_logout(args), needs_client=False)
+
+    p_whoami = sub.add_parser("whoami", help="Show which account and key are currently active")
+    _add_global(p_whoami)
+    p_whoami.add_argument("--api-base", dest="api_base", default=None,
+                          help="Inspect the credential for a non-default API base URL.")
+    p_whoami.set_defaults(func=lambda client, args: cmd_whoami(args), needs_client=False)
+
     p_account = sub.add_parser("account", help="Show plan limits and available services")
     _add_global(p_account)
     p_account.set_defaults(func=cmd_account)
@@ -740,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)
@@ -789,6 +907,14 @@ def main(argv: Optional[List[str]] = None) -> None:
     func = getattr(args, "func", None)
     if func is None:
         parser.error("missing command (try `sonilo --help`)")
+    if getattr(args, "needs_client", True) is False:
+        try:
+            func(None, args)  # type: ignore[arg-type]
+        except LoginError as exc:
+            # Expected outcomes — denied, expired, throttled, offline — read as
+            # `sonilo: <message>`, never as a traceback.
+            _fail(str(exc))
+        return
     client = build_client(getattr(args, "api_key", None))
     try:
         func(client, args)

sonilo_cli-0.12.0/src/sonilo_cli/credentials.py

@@ -0,0 +1,105 @@
+"""The credential file written by `sonilo login`.
+
+Format and location are shared with the JS CLI (`packages/cli/src/credentials.ts`
+in sonilo-js) and read by sonilo-mcp, so the path, the JSON shape and the
+0600/0700 modes are a cross-repo contract — change them in all three or not at
+all.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+DEFAULT_API_BASE = "https://api.sonilo.com"
+FORMAT_VERSION = 1
+
+
+class CredentialFormatError(Exception):
+    """The file was written by a newer client than this one understands."""
+
+
+def credentials_path() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME")
+    root = Path(base) if base else Path(os.environ.get("HOME", str(Path.home()))) / ".config"
+    return root / "sonilo" / "credentials.json"
+
+
+def _empty() -> Dict[str, Any]:
+    return {"version": FORMAT_VERSION, "credentials": {}}
+
+
+def _load(path: Path) -> Dict[str, Any]:
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError:
+        return _empty()
+    try:
+        parsed = json.loads(raw)
+    except ValueError:
+        # Corrupt file reads as "no credential"; `login` will replace it.
+        return _empty()
+    if not isinstance(parsed, dict):
+        return _empty()
+    version = parsed.get("version")
+    if isinstance(version, int) and version > FORMAT_VERSION:
+        raise CredentialFormatError(
+            f"{path} was written by a newer sonilo CLI (format {version}). "
+            "Upgrade the CLI or delete the file."
+        )
+    creds = parsed.get("credentials")
+    return {
+        "version": FORMAT_VERSION,
+        "credentials": creds if isinstance(creds, dict) else {},
+    }
+
+
+def _save(path: Path, data: Dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    os.chmod(path.parent, 0o700)
+    tmp = path.with_name(path.name + ".{}.tmp".format(os.getpid()))
+    tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    os.chmod(tmp, 0o600)
+    try:
+        # Rename last: an interrupted write can never replace a whole
+        # credential with half of one.
+        os.replace(tmp, path)
+    except OSError:
+        # Never leave the temp file behind holding a live key.
+        try:
+            tmp.unlink()
+        except OSError:
+            pass
+        raise
+
+
+def read_credential(api_base: str, path: Optional[Path] = None) -> Optional[Dict[str, Any]]:
+    entry = _load(path or credentials_path())["credentials"].get(api_base)
+    if isinstance(entry, dict) and isinstance(entry.get("api_key"), str) and entry["api_key"]:
+        return entry
+    return None
+
+
+def write_credential(
+    api_base: str, cred: Dict[str, Any], path: Optional[Path] = None
+) -> None:
+    target = path or credentials_path()
+    data = _load(target)
+    data["credentials"][api_base] = cred
+    _save(target, data)
+
+
+def remove_credential(api_base: str, path: Optional[Path] = None) -> None:
+    target = path or credentials_path()
+    data = _load(target)
+    if api_base not in data["credentials"]:
+        return
+    del data["credentials"][api_base]
+    if not data["credentials"]:
+        try:
+            target.unlink()
+        except OSError:
+            pass
+        return
+    _save(target, data)