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

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

@@ -1,3 +1,19 @@
+Metadata-Version: 2.5
+Name: sonilo-cli
+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
+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.15,>=0.14.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.
@@ -82,6 +98,8 @@ production sign-in coexist without overwriting each other.
     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>
@@ -225,6 +243,23 @@ call instead.)
   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:
@@ -251,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.12.0/PKG-INFO → sonilo_cli-0.13.0/README.md

@@ -1,19 +1,3 @@
-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.
@@ -98,6 +82,8 @@ production sign-in coexist without overwriting each other.
     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>
@@ -241,6 +227,23 @@ call instead.)
   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:
@@ -267,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.12.0 → sonilo_cli-0.13.0}/pyproject.toml

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

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

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

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

@@ -510,6 +510,51 @@ def cmd_audio_ducking(client: Sonilo, args: argparse.Namespace) -> None:
     _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
@@ -858,6 +903,32 @@ def build_parser() -> argparse.ArgumentParser:
     )
     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.12.0 → sonilo_cli-0.13.0}/tests/test_cli.py

@@ -1346,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