sonilo 0.1.0__tar.gz

sonilo-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest

sonilo-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      # PyPI Trusted Publishing (OIDC). No PYPI_TOKEN secret needed.
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]" build
+      - run: pytest
+      - name: Verify tag matches pyproject version
+        if: github.ref_type == 'tag'
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "Tag version ($TAG_VERSION) does not match pyproject version ($PKG_VERSION)"
+            exit 1
+          fi
+      - run: python -m build
+      - name: Publish to PyPI
+        # Authenticates via OIDC Trusted Publishing — configured as a pending
+        # publisher for project `sonilo` (repo sonilo-python, workflow publish.yml).
+        # Tag refs only: a workflow_dispatch on a branch runs tests/build but
+        # never publishes. To retry a failed publish, dispatch on the tag:
+        # gh workflow run publish.yml --ref vX.Y.Z
+        if: github.ref_type == 'tag'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

sonilo-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.DS_Store

sonilo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sonilo AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sonilo-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: sonilo
+Version: 0.1.0
+Summary: Official Python client for the Sonilo API
+Project-URL: Repository, https://github.com/sonilo-ai/sonilo-python
+Author: Sonilo AI
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,generation,music,sonilo,text-to-music,video-to-music
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sonilo
+
+Official Python client for the [Sonilo](https://sonilo.com) API.
+Python ≥ 3.9. Sync and async clients included.
+
+## Installation
+
+```bash
+pip install sonilo
+```
+
+## Quickstart
+
+```python
+from sonilo import Sonilo
+
+client = Sonilo()  # reads SONILO_API_KEY
+
+track = client.text_to_music.generate(
+    prompt="cinematic orchestral score",
+    duration=60,
+)
+track.save("output.mp3")
+print(track.title)
+```
+
+## Video to music
+
+```python
+track = client.video_to_music.generate(video="my_video.mp4", prompt="upbeat")
+# or bytes / an open binary file, or a hosted URL:
+track = client.video_to_music.generate(video_url="https://example.com/clip.mp4")
+```
+
+## Streaming
+
+```python
+for event in client.text_to_music.stream(prompt="lofi", duration=30):
+    if event["type"] == "audio_chunk":
+        handle(event["data"])  # bytes, as they arrive
+```
+
+## Async
+
+```python
+from sonilo import AsyncSonilo
+
+async with AsyncSonilo() as client:
+    track = await client.text_to_music.generate(prompt="lofi", duration=30)
+    async for event in client.text_to_music.stream(prompt="lofi", duration=30):
+        ...
+```
+
+## Segments
+
+Shape the composition with start-only contiguous segments (each ends where
+the next begins):
+
+```python
+client.text_to_music.generate(
+    prompt="epic trailer",
+    duration=60,
+    segments=[
+        {"start": 0, "prompt": "soft intro", "label": "intro"},
+        {"start": 20, "prompt": "building tension", "label": "verse"},
+        {"start": 40, "prompt": "full orchestra", "label": "chorus"},
+    ],
+)
+```
+
+## Account
+
+```python
+client.account.services()
+client.account.usage(days=7)
+```
+
+## Errors
+
+All errors extend `SoniloError`: `AuthenticationError` (401),
+`PaymentRequiredError` (402), `RateLimitError` (429, `.retry_after`),
+`BadRequestError` (400/413/422, `.detail`), `APIError` (anything else),
+and `GenerationError` for failures mid-stream.
+
+## License
+
+MIT

sonilo-0.1.0/README.md

@@ -0,0 +1,87 @@
+# sonilo
+
+Official Python client for the [Sonilo](https://sonilo.com) API.
+Python ≥ 3.9. Sync and async clients included.
+
+## Installation
+
+```bash
+pip install sonilo
+```
+
+## Quickstart
+
+```python
+from sonilo import Sonilo
+
+client = Sonilo()  # reads SONILO_API_KEY
+
+track = client.text_to_music.generate(
+    prompt="cinematic orchestral score",
+    duration=60,
+)
+track.save("output.mp3")
+print(track.title)
+```
+
+## Video to music
+
+```python
+track = client.video_to_music.generate(video="my_video.mp4", prompt="upbeat")
+# or bytes / an open binary file, or a hosted URL:
+track = client.video_to_music.generate(video_url="https://example.com/clip.mp4")
+```
+
+## Streaming
+
+```python
+for event in client.text_to_music.stream(prompt="lofi", duration=30):
+    if event["type"] == "audio_chunk":
+        handle(event["data"])  # bytes, as they arrive
+```
+
+## Async
+
+```python
+from sonilo import AsyncSonilo
+
+async with AsyncSonilo() as client:
+    track = await client.text_to_music.generate(prompt="lofi", duration=30)
+    async for event in client.text_to_music.stream(prompt="lofi", duration=30):
+        ...
+```
+
+## Segments
+
+Shape the composition with start-only contiguous segments (each ends where
+the next begins):
+
+```python
+client.text_to_music.generate(
+    prompt="epic trailer",
+    duration=60,
+    segments=[
+        {"start": 0, "prompt": "soft intro", "label": "intro"},
+        {"start": 20, "prompt": "building tension", "label": "verse"},
+        {"start": 40, "prompt": "full orchestra", "label": "chorus"},
+    ],
+)
+```
+
+## Account
+
+```python
+client.account.services()
+client.account.usage(days=7)
+```
+
+## Errors
+
+All errors extend `SoniloError`: `AuthenticationError` (401),
+`PaymentRequiredError` (402), `RateLimitError` (429, `.retry_after`),
+`BadRequestError` (400/413/422, `.detail`), `APIError` (anything else),
+and `GenerationError` for failures mid-stream.
+
+## License
+
+MIT

sonilo-0.1.0/examples/generate.py

@@ -0,0 +1,14 @@
+"""Usage: SONILO_API_KEY=sk_... python examples/generate.py "lofi beat" 30"""
+import sys
+
+from sonilo import Sonilo
+
+prompt = sys.argv[1] if len(sys.argv) > 1 else "cinematic orchestral score"
+duration = int(sys.argv[2]) if len(sys.argv) > 2 else 60
+
+with Sonilo() as client:
+    track = client.text_to_music.generate(prompt=prompt, duration=duration)
+
+out = track.save("output.mp3")
+title = f' — "{track.title}"' if track.title else ""
+print(f"Saved {out} ({len(track.audio)} bytes){title}")

sonilo-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sonilo"
+version = "0.1.0"
+description = "Official Python client for the Sonilo API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Sonilo AI" }]
+dependencies = ["httpx>=0.27"]
+keywords = ["sonilo", "music", "generation", "text-to-music", "video-to-music", "ai"]
+
+[project.urls]
+Repository = "https://github.com/sonilo-ai/sonilo-python"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "respx>=0.21"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sonilo"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

sonilo-0.1.0/src/sonilo/__init__.py

@@ -0,0 +1,29 @@
+from sonilo._async_client import AsyncSonilo
+from sonilo._client import Sonilo
+from sonilo._version import __version__
+from sonilo.errors import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    GenerationError,
+    PaymentRequiredError,
+    RateLimitError,
+    SoniloError,
+)
+from sonilo.types import Segment, StreamEvent, Track
+
+__all__ = [
+    "APIError",
+    "AsyncSonilo",
+    "AuthenticationError",
+    "BadRequestError",
+    "GenerationError",
+    "PaymentRequiredError",
+    "RateLimitError",
+    "Segment",
+    "Sonilo",
+    "SoniloError",
+    "StreamEvent",
+    "Track",
+    "__version__",
+]

sonilo-0.1.0/src/sonilo/_async_client.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Dict, Optional
+
+import httpx
+
+from sonilo._client import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, _default_headers, _resolve_api_key
+from sonilo._streaming import aiter_events
+from sonilo.errors import error_from_response
+from sonilo.resources.account import AsyncAccount
+from sonilo.resources.text_to_music import AsyncTextToMusic
+from sonilo.resources.video_to_music import AsyncVideoToMusic
+from sonilo.types import StreamEvent
+
+
+class AsyncSonilo:
+    """Asynchronous Sonilo API client."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        key = _resolve_api_key(api_key)
+        self._http = httpx.AsyncClient(
+            base_url=(base_url or DEFAULT_BASE_URL).rstrip("/"),
+            headers=_default_headers(key, "sdk-python"),
+            timeout=timeout,
+        )
+        self.text_to_music = AsyncTextToMusic(self)
+        self.video_to_music = AsyncVideoToMusic(self)
+        self.account = AsyncAccount(self)
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncSonilo":
+        return self
+
+    async def __aexit__(self, *exc_info: Any) -> None:
+        await self.close()
+
+    # -- internal transport -------------------------------------------------
+
+    async def _get_json(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        response = await self._http.get(path, params=params)
+        if response.status_code >= 400:
+            raise error_from_response(response)
+        return response.json()
+
+    async def _stream_events(
+        self,
+        path: str,
+        *,
+        data: Dict[str, str],
+        files: Optional[Dict[str, tuple]] = None,
+        close_after: Any = None,
+    ) -> AsyncIterator[StreamEvent]:
+        try:
+            async with self._http.stream("POST", path, data=data, files=files) as response:
+                if response.status_code >= 400:
+                    await response.aread()
+                    raise error_from_response(response)
+                async for event in aiter_events(response.aiter_text()):
+                    yield event
+        finally:
+            if close_after is not None:
+                close_after.close()

sonilo-0.1.0/src/sonilo/_client.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Iterator, Optional
+
+import httpx
+
+from sonilo._streaming import iter_events
+from sonilo._version import __version__
+from sonilo.errors import SoniloError, error_from_response
+from sonilo.resources.account import Account
+from sonilo.resources.text_to_music import TextToMusic
+from sonilo.resources.video_to_music import VideoToMusic
+from sonilo.types import StreamEvent
+
+DEFAULT_BASE_URL = "https://api.sonilo.com"
+DEFAULT_TIMEOUT = 600.0
+
+
+def _resolve_api_key(api_key: Optional[str]) -> str:
+    key = api_key or os.environ.get("SONILO_API_KEY")
+    if not key:
+        raise SoniloError(
+            "Missing API key: pass api_key= or set the SONILO_API_KEY environment variable"
+        )
+    return key
+
+
+def _default_headers(api_key: str, client_name: str) -> Dict[str, str]:
+    return {
+        "Authorization": f"Bearer {api_key}",
+        "X-Sonilo-Client": client_name,
+        "X-Sonilo-Client-Version": __version__,
+    }
+
+
+class Sonilo:
+    """Synchronous Sonilo API client."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        key = _resolve_api_key(api_key)
+        self._http = httpx.Client(
+            base_url=(base_url or DEFAULT_BASE_URL).rstrip("/"),
+            headers=_default_headers(key, "sdk-python"),
+            timeout=timeout,
+        )
+        self.text_to_music = TextToMusic(self)
+        self.video_to_music = VideoToMusic(self)
+        self.account = Account(self)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Sonilo":
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()
+
+    # -- internal transport -------------------------------------------------
+
+    def _get_json(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        response = self._http.get(path, params=params)
+        if response.status_code >= 400:
+            raise error_from_response(response)
+        return response.json()
+
+    def _stream_events(
+        self,
+        path: str,
+        *,
+        data: Dict[str, str],
+        files: Optional[Dict[str, tuple]] = None,
+        close_after: Any = None,
+    ) -> Iterator[StreamEvent]:
+        try:
+            with self._http.stream("POST", path, data=data, files=files) as response:
+                if response.status_code >= 400:
+                    response.read()
+                    raise error_from_response(response)
+                for event in iter_events(response.iter_text()):
+                    yield event
+        finally:
+            if close_after is not None:
+                close_after.close()

sonilo-0.1.0/src/sonilo/_requests.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from sonilo.errors import SoniloError
+from sonilo.types import Segment
+
+DEFAULT_FILENAME = "video.mp4"
+
+
+def build_t2m_data(
+    prompt: str, duration: int, segments: Optional[List[Segment]]
+) -> Dict[str, str]:
+    data = {"prompt": prompt, "duration": str(duration)}
+    if segments is not None:
+        data["segments"] = json.dumps(segments)
+    return data
+
+
+def normalize_video(video: Any) -> Tuple[str, Any, bool]:
+    """Normalize a video input into (filename, httpx-uploadable, opened_here).
+
+    Accepts a filesystem path (str/Path — opened for streaming upload; the
+    caller must close it, signalled by opened_here=True), raw bytes, or a
+    binary file-like object.
+    """
+    if isinstance(video, (str, Path)):
+        path = Path(video)
+        return path.name or DEFAULT_FILENAME, path.open("rb"), True
+    if isinstance(video, bytes):
+        return DEFAULT_FILENAME, video, False
+    if hasattr(video, "read"):
+        raw_name = getattr(video, "name", None)
+        filename = Path(raw_name).name if isinstance(raw_name, str) and raw_name else DEFAULT_FILENAME
+        return filename, video, False
+    raise SoniloError("Unsupported video input: pass a path, bytes, or a binary file object")
+
+
+def build_v2m_parts(
+    video: Any,
+    video_url: Optional[str],
+    prompt: Optional[str],
+    segments: Optional[List[Segment]],
+) -> Tuple[Dict[str, str], Optional[Dict[str, tuple]], bool]:
+    if (video is None) == (video_url is None):
+        raise SoniloError("Provide exactly one of video or video_url")
+
+    # Assemble data dict completely before opening any files
+    data: Dict[str, str] = {}
+    if video_url is not None:
+        data["video_url"] = video_url  # type: ignore[assignment]
+    if prompt is not None:
+        data["prompt"] = prompt
+    if segments is not None:
+        data["segments"] = json.dumps(segments)
+
+    # Now open files (only after data is fully assembled)
+    files: Optional[Dict[str, tuple]] = None
+    opened = False
+    if video is not None:
+        filename, fileobj, opened = normalize_video(video)
+        files = {"video": (filename, fileobj, "video/mp4")}
+
+    return data, files, opened

sonilo-0.1.0/src/sonilo/_streaming.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import base64
+import json
+from typing import AsyncIterable, AsyncIterator, Dict, Iterable, Iterator, List, Optional
+
+from sonilo.errors import GenerationError
+from sonilo.types import StreamEvent, Track
+
+
+def _parse_line(line: str) -> StreamEvent:
+    event = json.loads(line)
+    if event.get("type") == "audio_chunk" and isinstance(event.get("data"), str):
+        event = {**event, "data": base64.b64decode(event["data"])}
+    return event
+
+
+class _LineBuffer:
+    """Accumulates text chunks and yields complete NDJSON lines."""
+
+    def __init__(self) -> None:
+        self._buf = ""
+
+    def feed(self, text: str) -> Iterator[StreamEvent]:
+        self._buf += text
+        while True:
+            idx = self._buf.find("\n")
+            if idx == -1:
+                return
+            line, self._buf = self._buf[:idx].strip(), self._buf[idx + 1 :]
+            if line:
+                yield _parse_line(line)
+
+    def flush(self) -> Iterator[StreamEvent]:
+        line, self._buf = self._buf.strip(), ""
+        if line:
+            yield _parse_line(line)
+
+
+def iter_events(text_chunks: Iterable[str]) -> Iterator[StreamEvent]:
+    buf = _LineBuffer()
+    for chunk in text_chunks:
+        yield from buf.feed(chunk)
+    yield from buf.flush()
+
+
+async def aiter_events(text_chunks: AsyncIterable[str]) -> AsyncIterator[StreamEvent]:
+    buf = _LineBuffer()
+    async for chunk in text_chunks:
+        for event in buf.feed(chunk):
+            yield event
+    for event in buf.flush():
+        yield event
+
+
+class _TrackBuilder:
+    def __init__(self) -> None:
+        self._chunks: List[bytes] = []
+        self._title: Optional[str] = None
+        self._cost: Optional[Dict[str, str]] = None
+        self._complete = False
+
+    def add(self, event: StreamEvent) -> None:
+        event_type = event.get("type")
+        if event_type == "audio_chunk" and isinstance(event.get("data"), bytes):
+            self._chunks.append(event["data"])
+        elif event_type == "title" and isinstance(event.get("title"), str):
+            self._title = event["title"]
+        elif event_type == "cost":
+            self._cost = {k: v for k, v in event.items() if k != "type"}
+        elif event_type == "error":
+            message = event.get("message") or "generation failed"
+            code = event.get("code")
+            raise GenerationError(str(message), code=code if isinstance(code, str) else None)
+        elif event_type == "complete":
+            self._complete = True
+        # unknown event types: ignored
+
+    def build(self) -> Track:
+        if not self._complete:
+            raise GenerationError("stream ended before a 'complete' event (truncated response)")
+        return Track(audio=b"".join(self._chunks), title=self._title, cost=self._cost)
+
+
+def collect_track(events: Iterable[StreamEvent]) -> Track:
+    builder = _TrackBuilder()
+    try:
+        for event in events:
+            builder.add(event)
+    finally:
+        close = getattr(events, "close", None)
+        if close is not None:
+            close()
+    return builder.build()
+
+
+async def acollect_track(events: AsyncIterable[StreamEvent]) -> Track:
+    builder = _TrackBuilder()
+    try:
+        async for event in events:
+            builder.add(event)
+    finally:
+        aclose = getattr(events, "aclose", None)
+        if aclose is not None:
+            await aclose()
+    return builder.build()

sonilo-0.1.0/src/sonilo/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"