breeze-blue 0.1.0__tar.gz

breeze_blue-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- ElevenLabs-compatible client surface for text-to-speech, voices, text-to-voice, history, models, and account APIs.
+- Typed errors for authentication, rate limiting, validation, billing, upstream, and service-unavailable failures.
+- Audio playback helpers using ffplay, afplay on macOS, and mpv for streaming-style playback.
+- `xi-api-key` auth header and `x-breeze-sdk` telemetry header.

breeze_blue-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Breeze Blue
+
+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.

breeze_blue-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include CHANGELOG.md
+include LICENSE
+include README.md
+prune tests
+prune src/*.egg-info

breeze_blue-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: breeze-blue
+Version: 0.1.0
+Summary: Python SDK for the Breeze Blue Developer API.
+Author-email: Breeze Blue <support@breeze.blue>
+License-Expression: MIT
+Project-URL: Homepage, https://breeze.blue
+Project-URL: Documentation, https://breeze.blue/docs
+Keywords: audio,breeze,breeze-blue,elevenlabs,elevenlabs-alternative,sdk,text-to-speech,tts,voice
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1.0.0,>=0.28.0
+Dynamic: license-file
+
+# Breeze Blue Python SDK
+
+Local v0.1 Python SDK for the Breeze Blue Developer API.
+
+## Install
+
+Before the package is published to PyPI, install it from this monorepo:
+
+```bash
+uv sync
+uv pip install -e ./packages/breeze-python
+```
+
+After the first public release, install the same SDK from PyPI:
+
+```bash
+uv add breeze-blue
+```
+
+```python
+from breeze_blue import BreezeBlue, play, save, stream
+
+client = BreezeBlue()  # Reads BREEZE_API_KEY and defaults to https://api.breeze.blue
+
+audio = client.text_to_speech.convert(
+    "voc_demo",
+    text="Hello from Breeze Blue.",
+    output_format="mp3_44100_128",
+)
+play(audio)
+save(audio, "hello.mp3")
+```
+
+## Client
+
+```python
+client = BreezeBlue(
+    api_key="brz_secret",
+    base_url="https://api.breeze.blue",
+)
+```
+
+Authentication uses the ElevenLabs-compatible `xi-api-key` header to make migration easier. If `api_key` is omitted, the SDK reads `BREEZE_API_KEY`. If `base_url` is omitted, the SDK reads `BREEZE_BASE_URL` and then falls back to `https://api.breeze.blue`.
+
+For local development, pass `base_url="http://127.0.0.1:8000"` or set `BREEZE_BASE_URL`.
+
+Set a default client timeout with `BreezeBlue(timeout=120.0)`, or override a single call with `timeout=120.0`.
+
+## Resources
+
+- `client.text_to_speech.convert(voice_id, text=...)`
+- `client.text_to_speech.stream(voice_id, text=...)`
+- `client.voices.search(...)`
+- `client.voices.get(voice_id)`
+- `client.voices.ivc.create_preview(name=..., file=...)`
+- `client.voices.ivc.edit(voice_id, name=..., file=...)`
+- `client.voices.ivc.get_settings(voice_id)` / `client.voices.ivc.update_settings(voice_id, guidance_scale=...)`
+- `client.voices.ivc.delete(voice_id)`
+- `client.text_to_voice.design(voice_description=...)`
+- `client.text_to_voice.create(generated_voice_id=..., voice_name=...)`
+- `client.text_to_voice.stream_preview(generated_voice_id)`
+- `client.history.list(...)`
+- `client.history.get(history_item_id)`
+- `client.history.download_audio(history_item_id)`
+- `client.history.delete(history_item_id)`
+- `client.models.list()`
+- `client.account.balance()`
+- `client.account.usage(...)`
+
+All resource methods accept `timeout=<seconds>` to override the client default for a single call.
+Common response shapes are exported as `TypedDict` types from `breeze_blue.types` and from the package root.
+
+## Audio Helpers
+
+Audio endpoints return `AudioResponse` with:
+
+- `content`
+- `content_type`
+- `history_item_id`
+
+Helpers:
+
+- `audio.save(path)`
+- `audio.play()` uses `ffplay`, with macOS `afplay` fallback, and waits for playback to finish.
+- `audio.stream()` pipes the buffered response content to `mpv` and waits for playback to finish.
+- `play(audio)`, `save(audio, path)`, and `stream(audio)` are also exported
+  from `breeze_blue` for ElevenLabs-style examples.
+- `stream(audio)` also accepts an iterable of byte chunks for chunked playback.
+- `start_play(audio)` and `start_stream(audio)` are available for advanced
+  fire-and-forget process control.
+
+## Errors
+
+All API errors inherit from `BreezeBlueError`. HTTP and Breeze error codes are mapped to typed exceptions including `BadRequestError`, `AuthenticationError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `ValidationError`, `RateLimitError`, `BillingInsufficientCreditsError`, `UpstreamError`, and `ServiceUnavailableError`.
+
+## Local release workflow
+
+The Python and TypeScript SDKs share one SemVer version. From the monorepo root:
+
+```bash
+mise exec -- pnpm sdk:status
+mise exec -- pnpm sdk:version patch
+mise exec -- pnpm sdk:check
+mise exec -- pnpm sdk:build
+mise exec -- pnpm sdk:smoke
+mise exec -- pnpm sdk:publish -- --dry-run
+```
+
+Use `patch` for compatible bug fixes, `minor` for compatible new features, and `major` only for breaking public API changes. Actual PyPI publishing uses local `uv publish` credentials, such as `UV_PUBLISH_TOKEN`; do not store tokens in the repo.

breeze_blue-0.1.0/README.md

@@ -0,0 +1,109 @@
+# Breeze Blue Python SDK
+
+Local v0.1 Python SDK for the Breeze Blue Developer API.
+
+## Install
+
+Before the package is published to PyPI, install it from this monorepo:
+
+```bash
+uv sync
+uv pip install -e ./packages/breeze-python
+```
+
+After the first public release, install the same SDK from PyPI:
+
+```bash
+uv add breeze-blue
+```
+
+```python
+from breeze_blue import BreezeBlue, play, save, stream
+
+client = BreezeBlue()  # Reads BREEZE_API_KEY and defaults to https://api.breeze.blue
+
+audio = client.text_to_speech.convert(
+    "voc_demo",
+    text="Hello from Breeze Blue.",
+    output_format="mp3_44100_128",
+)
+play(audio)
+save(audio, "hello.mp3")
+```
+
+## Client
+
+```python
+client = BreezeBlue(
+    api_key="brz_secret",
+    base_url="https://api.breeze.blue",
+)
+```
+
+Authentication uses the ElevenLabs-compatible `xi-api-key` header to make migration easier. If `api_key` is omitted, the SDK reads `BREEZE_API_KEY`. If `base_url` is omitted, the SDK reads `BREEZE_BASE_URL` and then falls back to `https://api.breeze.blue`.
+
+For local development, pass `base_url="http://127.0.0.1:8000"` or set `BREEZE_BASE_URL`.
+
+Set a default client timeout with `BreezeBlue(timeout=120.0)`, or override a single call with `timeout=120.0`.
+
+## Resources
+
+- `client.text_to_speech.convert(voice_id, text=...)`
+- `client.text_to_speech.stream(voice_id, text=...)`
+- `client.voices.search(...)`
+- `client.voices.get(voice_id)`
+- `client.voices.ivc.create_preview(name=..., file=...)`
+- `client.voices.ivc.edit(voice_id, name=..., file=...)`
+- `client.voices.ivc.get_settings(voice_id)` / `client.voices.ivc.update_settings(voice_id, guidance_scale=...)`
+- `client.voices.ivc.delete(voice_id)`
+- `client.text_to_voice.design(voice_description=...)`
+- `client.text_to_voice.create(generated_voice_id=..., voice_name=...)`
+- `client.text_to_voice.stream_preview(generated_voice_id)`
+- `client.history.list(...)`
+- `client.history.get(history_item_id)`
+- `client.history.download_audio(history_item_id)`
+- `client.history.delete(history_item_id)`
+- `client.models.list()`
+- `client.account.balance()`
+- `client.account.usage(...)`
+
+All resource methods accept `timeout=<seconds>` to override the client default for a single call.
+Common response shapes are exported as `TypedDict` types from `breeze_blue.types` and from the package root.
+
+## Audio Helpers
+
+Audio endpoints return `AudioResponse` with:
+
+- `content`
+- `content_type`
+- `history_item_id`
+
+Helpers:
+
+- `audio.save(path)`
+- `audio.play()` uses `ffplay`, with macOS `afplay` fallback, and waits for playback to finish.
+- `audio.stream()` pipes the buffered response content to `mpv` and waits for playback to finish.
+- `play(audio)`, `save(audio, path)`, and `stream(audio)` are also exported
+  from `breeze_blue` for ElevenLabs-style examples.
+- `stream(audio)` also accepts an iterable of byte chunks for chunked playback.
+- `start_play(audio)` and `start_stream(audio)` are available for advanced
+  fire-and-forget process control.
+
+## Errors
+
+All API errors inherit from `BreezeBlueError`. HTTP and Breeze error codes are mapped to typed exceptions including `BadRequestError`, `AuthenticationError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `ValidationError`, `RateLimitError`, `BillingInsufficientCreditsError`, `UpstreamError`, and `ServiceUnavailableError`.
+
+## Local release workflow
+
+The Python and TypeScript SDKs share one SemVer version. From the monorepo root:
+
+```bash
+mise exec -- pnpm sdk:status
+mise exec -- pnpm sdk:version patch
+mise exec -- pnpm sdk:check
+mise exec -- pnpm sdk:build
+mise exec -- pnpm sdk:smoke
+mise exec -- pnpm sdk:publish -- --dry-run
+```
+
+Use `patch` for compatible bug fixes, `minor` for compatible new features, and `major` only for breaking public API changes. Actual PyPI publishing uses local `uv publish` credentials, such as `UV_PUBLISH_TOKEN`; do not store tokens in the repo.

breeze_blue-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "breeze-blue"
+version = "0.1.0"
+description = "Python SDK for the Breeze Blue Developer API."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Breeze Blue", email = "support@breeze.blue" },
+]
+keywords = [
+  "audio",
+  "breeze",
+  "breeze-blue",
+  "elevenlabs",
+  "elevenlabs-alternative",
+  "sdk",
+  "text-to-speech",
+  "tts",
+  "voice",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Multimedia :: Sound/Audio :: Speech",
+]
+dependencies = [
+  "httpx>=0.28.0,<1.0.0",
+]
+
+[project.urls]
+Homepage = "https://breeze.blue"
+Documentation = "https://breeze.blue/docs"
+
+[dependency-groups]
+dev = [
+  "exceptiongroup>=1.2.0,<2.0.0; python_version < '3.11'",
+  "pyright>=1.1.407,<2.0.0",
+  "pytest>=8.4.2,<9.0.0",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

breeze_blue-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

breeze_blue-0.1.0/src/breeze_blue/__init__.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from ._audio import AudioResponse, play, save, start_play, start_stream, stream
+from ._client import BreezeBlue
+from ._errors import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    BillingInsufficientCreditsError,
+    BreezeBlueError,
+    ConflictError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    ServiceUnavailableError,
+    UpstreamError,
+    ValidationError,
+)
+from .types import (
+    Balance,
+    GenericStatus,
+    HistoryItem,
+    HistoryList,
+    Model,
+    Usage,
+    Voice,
+    VoiceClonePreview,
+    VoiceDesignResponse,
+    VoiceList,
+    VoiceSettings,
+)
+
+try:
+    __version__ = version("breeze-blue")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "APIError",
+    "AudioResponse",
+    "AuthenticationError",
+    "BadRequestError",
+    "BillingInsufficientCreditsError",
+    "BreezeBlue",
+    "BreezeBlueError",
+    "ConflictError",
+    "ForbiddenError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServiceUnavailableError",
+    "UpstreamError",
+    "ValidationError",
+    "Balance",
+    "GenericStatus",
+    "HistoryItem",
+    "HistoryList",
+    "Model",
+    "Usage",
+    "Voice",
+    "VoiceClonePreview",
+    "VoiceDesignResponse",
+    "VoiceList",
+    "VoiceSettings",
+    "__version__",
+    "play",
+    "save",
+    "start_play",
+    "start_stream",
+    "stream",
+]

breeze_blue-0.1.0/src/breeze_blue/_audio.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+import platform
+import shutil
+import subprocess
+
+
+class PlayerNotFoundError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class AudioResponse:
+    content: bytes
+    content_type: str | None = None
+    history_item_id: str | None = None
+
+    def save(self, path: str | Path) -> Path:
+        target = Path(path)
+        target.write_bytes(self.content)
+        return target
+
+    def play(self) -> None:
+        ffplay = shutil.which("ffplay")
+        if ffplay:
+            _pipe_to_player([ffplay, "-autoexit", "-nodisp", "-"], self.content)
+            return
+
+        if platform.system() == "Darwin":
+            afplay = shutil.which("afplay")
+            if afplay:
+                _pipe_to_player([afplay, "-"], self.content)
+                return
+
+        raise PlayerNotFoundError("Install ffplay, or afplay on macOS, to play audio.")
+
+    def stream(self) -> None:
+        mpv = shutil.which("mpv")
+        if not mpv:
+            raise PlayerNotFoundError("Install mpv to stream audio.")
+        _pipe_to_player([mpv, "--no-terminal", "-"], self.content)
+
+
+def save(audio: AudioResponse | bytes | bytearray, path: str | Path) -> Path:
+    return _coerce_audio_response(audio).save(path)
+
+
+def play(audio: AudioResponse | bytes | bytearray) -> None:
+    return _coerce_audio_response(audio).play()
+
+
+def stream(audio: AudioResponse | bytes | bytearray | Iterable[bytes]) -> None:
+    mpv = shutil.which("mpv")
+    if not mpv:
+        raise PlayerNotFoundError("Install mpv to stream audio.")
+    _pipe_chunks_to_player([mpv, "--no-terminal", "-"], _iter_audio_chunks(audio))
+
+
+def start_play(audio: AudioResponse | bytes | bytearray) -> subprocess.Popen[bytes]:
+    response = _coerce_audio_response(audio)
+    ffplay = shutil.which("ffplay")
+    if ffplay:
+        return _start_player([ffplay, "-autoexit", "-nodisp", "-"], response.content)
+    if platform.system() == "Darwin":
+        afplay = shutil.which("afplay")
+        if afplay:
+            return _start_player([afplay, "-"], response.content)
+    raise PlayerNotFoundError("Install ffplay, or afplay on macOS, to play audio.")
+
+
+def start_stream(audio: AudioResponse | bytes | bytearray | Iterable[bytes]) -> subprocess.Popen[bytes]:
+    mpv = shutil.which("mpv")
+    if not mpv:
+        raise PlayerNotFoundError("Install mpv to stream audio.")
+    return _start_player_with_chunks([mpv, "--no-terminal", "-"], _iter_audio_chunks(audio))
+
+
+def _coerce_audio_response(audio: AudioResponse | bytes | bytearray) -> AudioResponse:
+    if isinstance(audio, AudioResponse):
+        return audio
+    return AudioResponse(content=bytes(audio))
+
+
+def _iter_audio_chunks(audio: AudioResponse | bytes | bytearray | Iterable[bytes]) -> Iterable[bytes]:
+    if isinstance(audio, AudioResponse):
+        yield audio.content
+        return
+    if isinstance(audio, bytes | bytearray):
+        yield bytes(audio)
+        return
+    yield from audio
+
+
+def _pipe_to_player(command: list[str], audio: bytes) -> None:
+    process = _start_player(command, audio)
+    process.wait()
+
+
+def _pipe_chunks_to_player(command: list[str], chunks: Iterable[bytes]) -> None:
+    process = _start_player_with_chunks(command, chunks)
+    process.wait()
+
+
+def _start_player(command: list[str], audio: bytes) -> subprocess.Popen[bytes]:
+    return _start_player_with_chunks(command, [audio])
+
+
+def _start_player_with_chunks(command: list[str], chunks: Iterable[bytes]) -> subprocess.Popen[bytes]:
+    process = subprocess.Popen(command, stdin=subprocess.PIPE)
+    if process.stdin is not None:
+        for chunk in chunks:
+            if chunk:
+                process.stdin.write(chunk)
+        process.stdin.close()
+    return process

breeze_blue-0.1.0/src/breeze_blue/_client.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import os
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+
+import httpx
+
+from ._audio import AudioResponse
+from ._errors import raise_for_response
+from ._resources import AccountResource, HistoryResource, ModelsResource, TextToSpeechResource, TextToVoiceResource, VoicesResource
+
+
+DEFAULT_BASE_URL = "https://api.breeze.blue"
+try:
+    SDK_VERSION = version("breeze-blue")
+except PackageNotFoundError:
+    SDK_VERSION = "0.0.0"
+
+
+class BreezeBlue:
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout = 60.0,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self.api_key = api_key if api_key is not None else os.getenv("BREEZE_API_KEY")
+        resolved_base_url = base_url or os.getenv("BREEZE_BASE_URL") or DEFAULT_BASE_URL
+        self.base_url = resolved_base_url.rstrip("/")
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(timeout=timeout)
+
+        self.text_to_speech = TextToSpeechResource(self)
+        self.voices = VoicesResource(self)
+        self.text_to_voice = TextToVoiceResource(self)
+        self.history = HistoryResource(self)
+        self.models = ModelsResource(self)
+        self.account = AccountResource(self)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> BreezeBlue:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+        files: dict[str, Any] | list[tuple[str, Any]] | None = None,
+        timeout: float | httpx.Timeout | None = None,
+    ) -> httpx.Response:
+        request_kwargs: dict[str, Any] = {
+            "params": _drop_none(params),
+            "json": json,
+            "data": _drop_none(data),
+            "files": files,
+            "headers": self._headers(),
+        }
+        if timeout is not None:
+            request_kwargs["timeout"] = timeout
+        response = self._client.request(method, self._url(path), **request_kwargs)
+        raise_for_response(response)
+        return response
+
+    def json_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+        files: dict[str, Any] | list[tuple[str, Any]] | None = None,
+        timeout: float | httpx.Timeout | None = None,
+    ) -> Any:
+        response = self.request(method, path, params=params, json=json, data=data, files=files, timeout=timeout)
+        if not response.content:
+            return None
+        return response.json()
+
+    def audio_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        timeout: float | httpx.Timeout | None = None,
+    ) -> AudioResponse:
+        response = self.request(method, path, params=params, json=json, timeout=timeout)
+        return AudioResponse(
+            content=response.content,
+            content_type=response.headers.get("content-type"),
+            history_item_id=response.headers.get("history-item-id"),
+        )
+
+    def _url(self, path: str) -> str:
+        normalized = path if path.startswith("/") else f"/{path}"
+        return f"{self.base_url}{normalized}"
+
+    def _headers(self) -> dict[str, str]:
+        headers = {
+            "user-agent": f"breeze-blue-python/{SDK_VERSION}",
+            "x-breeze-sdk": f"breeze-blue-python/{SDK_VERSION}",
+        }
+        if self.api_key:
+            headers["xi-api-key"] = self.api_key
+        return headers
+
+
+def _drop_none(payload: dict[str, Any] | None) -> dict[str, Any] | None:
+    if payload is None:
+        return None
+    return {key: value for key, value in payload.items() if value is not None}