vocalbin 0.1.0__tar.gz

vocalbin-0.1.0/.env.example

@@ -0,0 +1 @@
+OPENAI_API_KEY=your_openai_api_key_here

vocalbin-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,109 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          version: "0.11.30"
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: Verify release tag
+        shell: bash
+        run: |
+          git fetch origin main
+          git merge-base --is-ancestor "$GITHUB_SHA" origin/main
+          tag_version="${GITHUB_REF_NAME#v}"
+          project_version="$(uv version --short)"
+          if [[ "$tag_version" != "$project_version" ]]; then
+            echo "Tag version $tag_version does not match project version $project_version."
+            exit 1
+          fi
+
+      - name: Install locked dependencies
+        run: uv sync --locked --dev --group release
+
+      - name: Run unit tests
+        run: uv run pytest
+
+      - name: Build distributions
+        run: uv build --out-dir dist
+
+      - name: Check distribution metadata
+        run: uv run twine check dist/*
+
+      - name: Smoke-test wheel
+        shell: bash
+        run: |
+          wheel="$(find dist -maxdepth 1 -type f -name '*.whl' -print -quit)"
+          if [[ -z "$wheel" ]]; then
+            echo "No wheel found in dist/."
+            exit 1
+          fi
+          uv venv --python 3.13 .smoke-venv
+          uv pip install --python .smoke-venv/bin/python "$wheel"
+          .smoke-venv/bin/python -c "import vocalbin; from importlib.metadata import version; print(version('vocalbin'))"
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/vocalbin
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@v1.14.0
+
+  github-release:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: >-
+          gh release create "$GITHUB_REF_NAME" dist/*
+          --repo "$GITHUB_REPOSITORY"
+          --verify-tag
+          --generate-notes
+          --title "$GITHUB_REF_NAME"

vocalbin-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,30 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  unit-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          version: "0.11.30"
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked --dev
+
+      - name: Run unit tests
+        run: uv run pytest

vocalbin-0.1.0/.gitignore

@@ -0,0 +1,86 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# ruff
+.ruff_cache/
+
+# IDEs
+.idea/
+.vscode/
+
+# Claude Code
+.claude/
+
+# OS
+.DS_Store
+Thumbs.db

vocalbin-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

vocalbin-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

vocalbin-0.1.0/AGENTS.md

@@ -0,0 +1,9 @@
+# Repository conventions
+
+- Use relative imports for package re-exports in `__init__.py`; use absolute imports in all other modules.
+- Model provider interfaces with `ABC` and `@abstractmethod`, not `Protocol`.
+- Keep provider ports in `vocalbin/ports.py`.
+- Keep credential loading in `vocalbin/credentials.py` and use `pydantic-settings`.
+- Avoid comments and docstrings that merely restate what the code already says.
+- Add a comment only when it explains a non-obvious reason, constraint, or tradeoff.
+- Do not add module docstrings that only summarize the module name or contents.

vocalbin-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing to vocalbin
+
+Thanks for your interest in improving `vocalbin`. This project is intentionally
+small: a typed, asynchronous wrapper around OpenAI's speech-to-text and
+text-to-speech endpoints. A small API surface, clear types, few dependencies and
+predictable behavior matter more than a long feature list.
+
+## Scope: read the Vision first
+
+Before opening an issue or pull request, please read [`vision.md`](vision.md). It
+defines what this library does, what it deliberately does **not** do, and the
+guardrails for future changes.
+
+A change is in scope only if you can answer **yes** to the five questions listed
+under _"Leitlinie für zukünftige Pull Requests"_ in [`vision.md`](vision.md) — in
+short:
+
+1. Does it directly support speech-to-text or text-to-speech via the OpenAI Audio API?
+2. Does it fit the existing request/response/port/client boundaries without adding
+   application-specific dependencies?
+3. Does the public API stay small, async, typed and understandable?
+4. Is the added dependency or complexity justified by a concrete benefit?
+5. Are behavior, validation and backward compatibility covered by tests?
+
+Work that needs audio processing, framework integration, persistence or
+orchestration belongs in the calling application or a separate package, not here.
+
+## Development setup
+
+```bash
+uv sync
+uv run pytest
+```
+
+Tests run offline against fake clients, so no `OPENAI_API_KEY` is required for the
+suite. A key is only needed to run the scripts in [`examples/`](examples/) against
+the real API.
+
+## Code conventions
+
+These follow [`AGENTS.md`](AGENTS.md):
+
+- Use relative imports for package re-exports in `__init__.py`; use absolute
+  imports everywhere else.
+- Model provider interfaces with `ABC` and `@abstractmethod`, not `Protocol`.
+  Keep the provider ports in `vocalbin/ports.py`.
+- Avoid comments and docstrings that merely restate the code. Add a comment only
+  when it explains a non-obvious reason, constraint or tradeoff.
+- Validate model capabilities up front (see `vocalbin/models.py`) and keep raw
+  provider data available on responses rather than discarding it.
+
+## Pull requests
+
+- Keep changes focused; split unrelated work into separate pull requests.
+- Add or update tests for any behavior, validation rule or capability change.
+- Update the [`README.md`](README.md) and the relevant script(s) in
+  [`examples/`](examples/) when you add or change a model, voice, format or
+  parameter.
+- Make sure `uv run pytest` passes before submitting.
+
+A pull request that widens the project's scope only because the implementation is
+technically possible here should be declined or split, as described in
+[`vision.md`](vision.md).

vocalbin-0.1.0/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.

vocalbin-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,141 @@
+# 🎙️ 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/deployment.md

@@ -0,0 +1,61 @@
+# Deployment
+
+`.github/workflows/release.yml` publishes `vocalbin` to PyPI when a `v*` tag is
+pushed. Authentication uses PyPI Trusted Publishing (OIDC); no API token is
+stored in GitHub.
+
+## One-time setup
+
+1. Create a GitHub environment named `pypi` under **Settings > Environments**.
+   Optionally require approval and restrict deployments to tags matching `v*`.
+2. Add a GitHub Trusted Publisher to the `vocalbin` project on PyPI:
+
+   | Setting | Value |
+   | --- | --- |
+   | Owner | `mathisarends` |
+   | Repository | `vocalbin` |
+   | Workflow | `release.yml` |
+   | Environment | `pypi` |
+
+If the PyPI project does not exist yet, create a pending publisher at
+<https://pypi.org/manage/account/publishing/> using the same values.
+
+## Release
+
+Set and commit the release version:
+
+```bash
+uv version 0.2.0
+uv run pytest
+git add pyproject.toml uv.lock
+git commit -m "Release 0.2.0"
+git push origin main
+```
+
+After the `Tests` workflow succeeds on `main`, create the matching tag:
+
+```bash
+version="$(uv version --short)"
+git tag -a "v$version" -m "Release v$version"
+git push origin "v$version"
+```
+
+The release workflow then:
+
+1. Confirms that the tagged commit belongs to `main` and the tag matches the
+   version in `pyproject.toml`.
+2. Installs the locked dependencies and runs all tests with 100% statement and
+   branch coverage.
+3. Builds the wheel and source distribution, checks their metadata, and installs
+   the wheel in a clean environment.
+4. Publishes the verified artifacts to PyPI through OIDC.
+5. Creates a GitHub Release with generated notes and both distributions attached.
+
+## Failures
+
+- PyPI versions are immutable. Fix a broken release with a new version; yank the
+  old version if necessary.
+- An OIDC error usually means the owner, repository, workflow, or environment
+  differs from the PyPI Trusted Publisher configuration.
+- A mismatched tag is rejected before publishing. Create a tag matching
+  `uv version --short`.