vocalbin 0.1.0__py3-none-any.whl

vocalbin/__init__.py

@@ -0,0 +1,33 @@
+from .clients import OpenAISpeechToText, OpenAITextToSpeech
+from .credentials import OpenAICredentials
+from .models import (
+    SpeechToTextFormat,
+    SpeechToTextModel,
+    SpeechToTextRequest,
+    SpeechToTextResponse,
+    TextToSpeechFormat,
+    TextToSpeechModel,
+    TextToSpeechRequest,
+    TextToSpeechResponse,
+    TextToSpeechVoice,
+    TimestampGranularity,
+)
+from .ports import SpeechToText, TextToSpeech
+
+__all__ = [
+    "OpenAICredentials",
+    "OpenAISpeechToText",
+    "OpenAITextToSpeech",
+    "SpeechToText",
+    "SpeechToTextFormat",
+    "SpeechToTextModel",
+    "SpeechToTextRequest",
+    "SpeechToTextResponse",
+    "TextToSpeech",
+    "TextToSpeechFormat",
+    "TextToSpeechModel",
+    "TextToSpeechRequest",
+    "TextToSpeechResponse",
+    "TextToSpeechVoice",
+    "TimestampGranularity",
+]

vocalbin/clients.py

@@ -0,0 +1,131 @@
+from types import TracebackType
+from typing import Any, Self, cast
+
+from openai import AsyncOpenAI, omit
+from openai.types.audio import TranscriptionCreateResponse
+
+from vocalbin.credentials import OpenAICredentials
+from vocalbin.models import (
+    SpeechToTextRequest,
+    SpeechToTextResponse,
+    TextToSpeechRequest,
+    TextToSpeechResponse,
+)
+from vocalbin.ports import SpeechToText, TextToSpeech
+
+_CONTENT_TYPES = {
+    "mp3": "audio/mpeg",
+    "opus": "audio/opus",
+    "aac": "audio/aac",
+    "flac": "audio/flac",
+    "wav": "audio/wav",
+    "pcm": "audio/pcm",
+}
+
+type TranscriptionResult = TranscriptionCreateResponse | str
+
+
+class _OpenAIClientOwner:
+    def __init__(self, api_key: str | None, client: AsyncOpenAI | None) -> None:
+        if api_key is not None and client is not None:
+            raise ValueError("Pass either 'api_key' or 'client', not both.")
+        if client is not None:
+            self.client = client
+        else:
+            resolved_api_key = (
+                api_key
+                if api_key is not None
+                else OpenAICredentials().api_key.get_secret_value()
+            )
+            self.client = AsyncOpenAI(api_key=resolved_api_key)
+        self._owns_client = client is None
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self.client.close()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+
+class OpenAITextToSpeech(_OpenAIClientOwner, TextToSpeech):
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        client: AsyncOpenAI | None = None,
+    ) -> None:
+        super().__init__(api_key, client)
+
+    async def synthesize(self, request: TextToSpeechRequest) -> TextToSpeechResponse:
+        result = await self.client.audio.speech.create(
+            input=request.text,
+            model=request.model,
+            voice=request.voice,
+            instructions=request.instructions if request.instructions is not None else omit,
+            response_format=request.response_format,
+            speed=request.speed if request.speed is not None else omit,
+        )
+
+        return TextToSpeechResponse(
+            audio=result.content,
+            model=request.model,
+            voice=request.voice,
+            response_format=request.response_format,
+            content_type=_CONTENT_TYPES[request.response_format],
+        )
+
+
+class OpenAISpeechToText(_OpenAIClientOwner, SpeechToText):
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        client: AsyncOpenAI | None = None,
+    ) -> None:
+        super().__init__(api_key, client)
+
+    async def transcribe(self, request: SpeechToTextRequest) -> SpeechToTextResponse:
+        params = request.to_openai_params()
+
+        if request.audio is not None:
+            file = (request.filename, request.audio)
+            result = cast(
+                TranscriptionResult,
+                await self.client.audio.transcriptions.create(file=file, **params),
+            )
+        else:
+            audio_path = request.audio_path
+            assert audio_path is not None
+            with audio_path.open("rb") as audio_file:
+                result = cast(
+                    TranscriptionResult,
+                    await self.client.audio.transcriptions.create(file=audio_file, **params),
+                )
+
+        return SpeechToTextResponse(
+            text=_extract_text(result),
+            model=request.model,
+            response_format=request.response_format,
+            raw=_serialize_result(result),
+        )
+
+
+def _extract_text(result: TranscriptionResult) -> str:
+    if isinstance(result, str):
+        return result
+    return result.text
+
+
+def _serialize_result(result: TranscriptionResult) -> dict[str, Any] | str:
+    if isinstance(result, str):
+        return result
+    return result.model_dump(mode="python")

vocalbin/credentials.py

@@ -0,0 +1,8 @@
+from pydantic import Field, SecretStr
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class OpenAICredentials(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="OPENAI_", extra="ignore")
+
+    api_key: SecretStr = Field(min_length=1)

vocalbin/models.py

@@ -0,0 +1,230 @@
+from enum import StrEnum
+from pathlib import Path
+from typing import Any, Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+
+class SpeechToTextModel(StrEnum):
+    GPT_4O_TRANSCRIBE = "gpt-4o-transcribe"
+    GPT_4O_MINI_TRANSCRIBE = "gpt-4o-mini-transcribe"
+    GPT_4O_TRANSCRIBE_DIARIZE = "gpt-4o-transcribe-diarize"
+    WHISPER_1 = "whisper-1"
+
+
+class SpeechToTextFormat(StrEnum):
+    JSON = "json"
+    TEXT = "text"
+    SRT = "srt"
+    VERBOSE_JSON = "verbose_json"
+    VTT = "vtt"
+    DIARIZED_JSON = "diarized_json"
+
+
+class TimestampGranularity(StrEnum):
+    WORD = "word"
+    SEGMENT = "segment"
+
+
+class TextToSpeechModel(StrEnum):
+    GPT_4O_MINI_TTS = "gpt-4o-mini-tts"
+    TTS_1 = "tts-1"
+    TTS_1_HD = "tts-1-hd"
+
+
+class TextToSpeechVoice(StrEnum):
+    ALLOY = "alloy"
+    ASH = "ash"
+    BALLAD = "ballad"
+    CORAL = "coral"
+    ECHO = "echo"
+    FABLE = "fable"
+    NOVA = "nova"
+    ONYX = "onyx"
+    SAGE = "sage"
+    SHIMMER = "shimmer"
+    VERSE = "verse"
+    MARIN = "marin"
+    CEDAR = "cedar"
+
+
+class TextToSpeechFormat(StrEnum):
+    MP3 = "mp3"
+    OPUS = "opus"
+    AAC = "aac"
+    FLAC = "flac"
+    WAV = "wav"
+    PCM = "pcm"
+
+
+class SpeechToTextRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    audio_path: Path | None = None
+    audio: bytes | None = Field(default=None, min_length=1, repr=False)
+    filename: str = Field(default="utterance.wav", min_length=1)
+    model: SpeechToTextModel = SpeechToTextModel.GPT_4O_TRANSCRIBE
+    response_format: SpeechToTextFormat = SpeechToTextFormat.JSON
+    language: str | None = Field(
+        default=None,
+        description="Optional ISO-639-1 language code such as 'de' or 'en'.",
+    )
+    prompt: str | None = None
+    temperature: float | None = Field(default=None, ge=0, le=1)
+    timestamp_granularities: list[TimestampGranularity] | None = None
+    include: list[Literal["logprobs"]] | None = None
+    chunking_strategy: Literal["auto"] | dict[str, Any] | None = None
+    extra_body: dict[str, Any] | None = None
+
+    @field_validator("audio_path")
+    @classmethod
+    def audio_path_must_be_a_file(cls, value: Path | None) -> Path | None:
+        if value is None:
+            return None
+        if not value.exists():
+            raise ValueError(f"Audio file does not exist: {value}")
+        if not value.is_file():
+            raise ValueError(f"Audio path is not a file: {value}")
+        return value
+
+    @field_validator("filename")
+    @classmethod
+    def filename_must_not_be_blank(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("filename must not be blank")
+        return value
+
+    @field_validator("language")
+    @classmethod
+    def language_must_be_iso_639_1(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        normalized = value.strip().lower()
+        if len(normalized) != 2 or not normalized.isalpha() or not normalized.isascii():
+            raise ValueError("language must be an ISO-639-1 code like 'de' or 'en'")
+        return normalized
+
+    @model_validator(mode="after")
+    def exactly_one_audio_source(self) -> Self:
+        if (self.audio_path is None) == (self.audio is None):
+            raise ValueError("Provide exactly one of 'audio_path' or 'audio'.")
+        return self
+
+    @model_validator(mode="after")
+    def validate_model_capabilities(self) -> Self:
+        gpt_transcribe_models = {
+            SpeechToTextModel.GPT_4O_TRANSCRIBE,
+            SpeechToTextModel.GPT_4O_MINI_TRANSCRIBE,
+        }
+
+        if self.model in gpt_transcribe_models:
+            supported = {SpeechToTextFormat.JSON, SpeechToTextFormat.TEXT}
+            if self.response_format not in supported:
+                raise ValueError(f"{self.model} supports only response_format json or text")
+
+        if self.model == SpeechToTextModel.GPT_4O_TRANSCRIBE_DIARIZE:
+            supported = {
+                SpeechToTextFormat.JSON,
+                SpeechToTextFormat.TEXT,
+                SpeechToTextFormat.DIARIZED_JSON,
+            }
+            if self.response_format not in supported:
+                raise ValueError(
+                    f"{self.model} supports only response_format json, text, or diarized_json"
+                )
+            if self.prompt is not None:
+                raise ValueError(f"{self.model} does not support prompt")
+            if self.include is not None:
+                raise ValueError(f"{self.model} does not support include/logprobs")
+            if self.timestamp_granularities is not None:
+                raise ValueError(f"{self.model} does not support timestamp_granularities")
+
+        if self.model == SpeechToTextModel.WHISPER_1:
+            supported = {
+                SpeechToTextFormat.JSON,
+                SpeechToTextFormat.TEXT,
+                SpeechToTextFormat.SRT,
+                SpeechToTextFormat.VERBOSE_JSON,
+                SpeechToTextFormat.VTT,
+            }
+            if self.response_format not in supported:
+                raise ValueError(
+                    f"{self.model} supports only response_format json, text, srt, "
+                    "verbose_json, or vtt"
+                )
+
+        if self.timestamp_granularities is not None:
+            if self.model != SpeechToTextModel.WHISPER_1:
+                raise ValueError("timestamp_granularities is supported only by whisper-1")
+            if self.response_format != SpeechToTextFormat.VERBOSE_JSON:
+                raise ValueError("timestamp_granularities requires response_format='verbose_json'")
+
+        if self.include is not None:
+            if self.model not in gpt_transcribe_models:
+                raise ValueError("include/logprobs is supported only by GPT transcription models")
+            if self.response_format != SpeechToTextFormat.JSON:
+                raise ValueError("include/logprobs requires response_format='json'")
+
+        return self
+
+    def to_openai_params(self) -> dict[str, Any]:
+        return self.model_dump(
+            exclude={"audio_path", "audio", "filename"},
+            exclude_none=True,
+            mode="json",
+        )
+
+
+class SpeechToTextResponse(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    text: str
+    model: SpeechToTextModel
+    response_format: SpeechToTextFormat
+    raw: dict[str, Any] | str
+
+
+class TextToSpeechRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    text: str = Field(min_length=1, max_length=4096)
+    model: TextToSpeechModel = TextToSpeechModel.GPT_4O_MINI_TTS
+    voice: TextToSpeechVoice = TextToSpeechVoice.MARIN
+    response_format: TextToSpeechFormat = TextToSpeechFormat.MP3
+    instructions: str | None = None
+    speed: float | None = Field(default=None, ge=0.25, le=4.0)
+
+    @field_validator("text")
+    @classmethod
+    def text_must_not_be_blank(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("text must not be blank")
+        return value
+
+    @model_validator(mode="after")
+    def validate_model_capabilities(self) -> Self:
+        legacy_models = {TextToSpeechModel.TTS_1, TextToSpeechModel.TTS_1_HD}
+        legacy_voices = {
+            TextToSpeechVoice.ALLOY,
+            TextToSpeechVoice.ASH,
+            TextToSpeechVoice.CORAL,
+            TextToSpeechVoice.ECHO,
+            TextToSpeechVoice.FABLE,
+            TextToSpeechVoice.ONYX,
+            TextToSpeechVoice.NOVA,
+            TextToSpeechVoice.SAGE,
+            TextToSpeechVoice.SHIMMER,
+        }
+        if self.model in legacy_models and self.voice not in legacy_voices:
+            raise ValueError(f"{self.model} does not support voice '{self.voice}'")
+        if self.model in legacy_models and self.instructions is not None:
+            raise ValueError(f"{self.model} does not support instructions")
+        return self
+
+
+class TextToSpeechResponse(BaseModel):
+    audio: bytes
+    model: TextToSpeechModel
+    voice: TextToSpeechVoice
+    response_format: TextToSpeechFormat
+    content_type: str

vocalbin/ports.py

@@ -0,0 +1,18 @@
+from abc import ABC, abstractmethod
+
+from vocalbin.models import (
+    SpeechToTextRequest,
+    SpeechToTextResponse,
+    TextToSpeechRequest,
+    TextToSpeechResponse,
+)
+
+
+class SpeechToText(ABC):
+    @abstractmethod
+    async def transcribe(self, request: SpeechToTextRequest) -> SpeechToTextResponse: ...
+
+
+class TextToSpeech(ABC):
+    @abstractmethod
+    async def synthesize(self, request: TextToSpeechRequest) -> TextToSpeechResponse: ...

vocalbin-0.1.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: vocalbin
+Version: 0.1.0
+Summary: Typed async wrappers for OpenAI speech-to-text and text-to-speech APIs
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: openai>=2.46.0
+Requires-Dist: pydantic-settings>=2.14.2
+Requires-Dist: pydantic>=2.13.4
+Description-Content-Type: text/markdown
+
+# 🎙️ vocalbin
+
+![vocalbin — typed, async voice for OpenAI](static/banner.png)
+
+`vocalbin` is a small, typed, asynchronous wrapper around OpenAI's speech-to-text
+and text-to-speech endpoints. It validates model capabilities up front, normalizes
+responses without discarding raw data, and stays independent of any
+application-specific settings or domain code.
+
+## Installation
+
+```bash
+uv add vocalbin
+```
+
+Set `OPENAI_API_KEY` in the environment, or pass an API key directly when creating
+a service. The default path reads the environment through `OpenAICredentials`:
+
+```python
+from vocalbin import OpenAICredentials
+
+credentials = OpenAICredentials()
+api_key = credentials.api_key.get_secret_value()
+```
+
+An explicit `api_key` takes precedence over the environment. An injected
+`AsyncOpenAI` client does not load credentials at all.
+
+## Speech to text
+
+```python
+from pathlib import Path
+
+from vocalbin import OpenAISpeechToText, SpeechToTextRequest
+
+
+async def transcribe() -> str:
+    async with OpenAISpeechToText() as speech_to_text:
+        response = await speech_to_text.transcribe(
+            SpeechToTextRequest(audio_path=Path("speech.wav"), language="de")
+        )
+    return response.text
+```
+
+Audio can also be supplied directly as bytes; `filename` only sets the multipart
+upload name:
+
+```python
+request = SpeechToTextRequest(audio=audio_bytes, filename="speech.wav")
+```
+
+Every request carries the transcript on `response.text` and the untouched provider
+payload on `response.raw` (a `dict` for JSON-like formats, a `str` for `text`,
+`srt` and `vtt`).
+
+## Text to speech
+
+```python
+from vocalbin import (
+    OpenAITextToSpeech,
+    TextToSpeechFormat,
+    TextToSpeechRequest,
+    TextToSpeechVoice,
+)
+
+
+async def synthesize() -> bytes:
+    async with OpenAITextToSpeech() as text_to_speech:
+        response = await text_to_speech.synthesize(
+            TextToSpeechRequest(
+                text="Hallo aus vocalbin!",
+                voice=TextToSpeechVoice.MARIN,
+                response_format=TextToSpeechFormat.MP3,
+                instructions="Sprich ruhig und freundlich.",
+            )
+        )
+    return response.audio
+```
+
+`response.content_type` gives the matching MIME type (e.g. `audio/mpeg`).
+
+## Supported models, voices and formats
+
+**Speech to text** — `gpt-4o-transcribe`, `gpt-4o-mini-transcribe`,
+`gpt-4o-transcribe-diarize`, `whisper-1`. Response formats and options are
+validated per model (for example, `timestamp_granularities` require `whisper-1`
+with `verbose_json`, and `include=["logprobs"]` requires a GPT transcription model
+with `json`).
+
+**Text to speech** — `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`; output formats `mp3`,
+`opus`, `aac`, `flac`, `wav`, `pcm`. The legacy `tts-1`/`tts-1-hd` models accept
+only the legacy voices and do not support `instructions`.
+
+## Examples
+
+The [`examples/`](examples/) directory holds runnable, integration-testable scripts
+that exercise every model/voice/format combination and double as documentation.
+With a valid `OPENAI_API_KEY` set:
+
+```bash
+uv run python examples/text_to_speech.py   # every TTS model, voice and format
+uv run python examples/speech_to_text.py   # every STT model and response format
+uv run python examples/round_trip.py       # synthesize -> transcribe, self-checking
+uv run python examples/shared_client.py    # one AsyncOpenAI client for both services
+```
+
+Generated audio and transcripts are written to `examples/output/` (git-ignored).
+`speech_to_text.py` synthesizes its own `sample.wav` on first run, so it needs no
+external audio file.
+
+## Bring your own client
+
+Both concrete services accept an existing `AsyncOpenAI` instance via `client=`,
+which lets you share one configured client (custom `base_url`, timeouts, retries)
+across both services. Injected clients remain owned by the caller and are not
+closed by `vocalbin`:
+
+```python
+from openai import AsyncOpenAI
+
+from vocalbin import OpenAISpeechToText, OpenAITextToSpeech
+
+client = AsyncOpenAI()
+tts = OpenAITextToSpeech(client=client)
+stt = OpenAISpeechToText(client=client)
+# ... use both, then close it yourself:
+await client.close()
+```
+
+## Ports
+
+The provider-independent `SpeechToText` and `TextToSpeech` ports are abstract base
+classes (`vocalbin/ports.py`). They mark the boundary of the library, so callers
+can depend on the interface rather than the OpenAI implementation.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```

vocalbin-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+vocalbin/__init__.py,sha256=WjVUZtzKobX1tgQhoVnDJ_6NCz_cIevS9hjeaPOCQNs,815
+vocalbin/clients.py,sha256=UIJoFPW7WbPIe0zEpjVwoxE5JHGVF9TFCmWbubfyn9I,4086
+vocalbin/credentials.py,sha256=0yv8mkRpmf_hyZyCwPpRgrF674CFKxm7DGhGBwg73V8,264
+vocalbin/models.py,sha256=VADhgJjJkW_kt7l2J3_u7so64lzYdko4jzID-d_4drI,8036
+vocalbin/ports.py,sha256=RrJRhF8pMSwTqv-TNKOBMzipy6GqepeceLepszAxcRQ,445
+vocalbin-0.1.0.dist-info/METADATA,sha256=mJ5YBhVIpRNkUmPkXn2DUENlqQOiEYP1rT6cl6YTeUc,4748
+vocalbin-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+vocalbin-0.1.0.dist-info/licenses/LICENSE,sha256=pcOfaJZcA1iM-OJrov7e6muy7zqtVvbl4CMAcyFD6rU,1069
+vocalbin-0.1.0.dist-info/RECORD,,

vocalbin-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

vocalbin-0.1.0.dist-info/licenses/LICENSE

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