tachyaudio 0.2.0b1__tar.gz

tachyaudio-0.2.0b1/.github/workflows/tests.yml

@@ -0,0 +1,59 @@
+name: tests
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+  workflow_dispatch:
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  linux:
+    name: Linux Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: python -m pip install .
+
+      - name: Run tests
+        run: python -m unittest discover -s tests
+
+      - name: Import smoke test
+        run: python -c "import tachyaudio as ta; assert ta.get_backend().name == 'miniaudio'; print(len(ta.list_devices()))"
+
+  macos:
+    name: macOS Python ${{ matrix.python-version }}
+    runs-on: macos-14
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: python -m pip install .
+
+      - name: Run tests
+        run: python -m unittest discover -s tests
+
+      - name: Import smoke test
+        run: python -c "import tachyaudio as ta; print(ta.get_backend().name); print(len(ta.list_devices()))"

tachyaudio-0.2.0b1/.github/workflows/wheels.yml

@@ -0,0 +1,54 @@
+name: wheels
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  linux:
+    name: Build Linux wheels
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install cibuildwheel
+        run: python -m pip install cibuildwheel
+
+      - name: Build wheels
+        run: python -m cibuildwheel --output-dir wheelhouse
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: linux-wheels
+          path: wheelhouse/*.whl
+
+  macos:
+    name: Build macOS wheels
+    runs-on: macos-14
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install cibuildwheel
+        run: python -m pip install cibuildwheel
+
+      - name: Build wheels
+        run: python -m cibuildwheel --output-dir wheelhouse
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: macos-wheels
+          path: wheelhouse/*.whl

tachyaudio-0.2.0b1/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+All notable changes to `tachyaudio` will be documented in this file.
+
+The project follows semantic versioning once releases begin. During `0.x`,
+public APIs may still change while the backend design stabilizes.
+
+## [Unreleased]
+
+## [0.2.0b1] - 2026-06-12
+
+### Added
+
+- Added the public `DuplexStream` API contract for backend-level full-duplex
+  capture and playback.
+- Added native macOS `DuplexStream` support backed by Core Audio input and
+  output queues owned by one native stream object.
+- Added native Linux `DuplexStream` support backed by one miniaudio duplex
+  device callback.
+
+### Changed
+
+- Promoted package metadata from pre-alpha to beta.
+- Kept wheel builds intentionally per-CPython-version rather than stable ABI.
+
+## [0.2.0a3] - 2026-06-12
+
+### Changed
+
+- Refactored native ring-buffer and stream-stat helpers without changing public
+  behavior.
+- Added `hardware_latency` to stream statistics. macOS reports Core Audio
+  device latency plus safety offset; Linux reports `None` until a reliable
+  miniaudio latency value is available.
+- Added blocking convenience helpers `OutputStream.write_all()` and
+  `InputStream.read_exactly()`.
+
+## [0.2.0a2] - 2026-06-10
+
+### Changed
+
+- Linux device enumeration now returns no devices instead of raising when
+  miniaudio cannot initialize or enumerate an audio backend in headless
+  containers.
+
+## [0.2.0a1] - 2026-06-10
+
+### Added
+
+- Linux native backend using vendored `miniaudio`.
+- Linux device enumeration through miniaudio.
+- Linux native output playback with a ring-buffer-backed `OutputStream`.
+- Linux native input capture with nonblocking `InputStream.read()`.
+- Linux CI coverage for Python 3.10 through 3.14.
+- Vendored miniaudio license attribution.
+
+### Changed
+
+- Linux backend initialization prefers PulseAudio, then falls back to ALSA.
+
+### Known Limitations
+
+- Linux support is new and has only been validated on a small set of Ubuntu
+  audio configurations.
+- Windows backend support is not implemented yet.
+- The API is pre-alpha and may change before a stable release.
+
+## [0.1.0] - 2026-06-10
+
+### Added
+
+- Initial Python package scaffold.
+- macOS Core Audio device enumeration.
+- macOS native output playback with a ring-buffer-backed `OutputStream`.
+- Finite playback helper via `tachyaudio.play()`.
+- Output stream lifecycle methods: `start()`, `stop()`, `drain()`, `flush()`,
+  and `close()`.
+- macOS native input capture with nonblocking `InputStream.read()`.
+- Stream statistics for processed frames, underruns, overruns, queued frames,
+  queued latency, and buffer size.
+- Playback and capture examples.
+- macOS CI and wheel workflow scaffolding for Python 3.10 through 3.14.
+
+### Known Limitations
+
+- Native backend support is currently macOS-only.
+- Windows and Linux backends are not implemented yet.
+- The API is pre-alpha and may change before the first PyPI release.

tachyaudio-0.2.0b1/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing
+
+`tachyaudio` is pre-alpha. The current implementation is intentionally narrow:
+macOS Core Audio device enumeration, output playback, and input capture.
+
+## Development setup
+
+Use Python 3.10 through 3.14.
+
+```bash
+python -m pip install -e .
+python -m unittest discover -s tests
+```
+
+On macOS, restricted sandboxes may hide Core Audio devices. Validate audio
+examples from an unsandboxed terminal before treating empty device lists as bugs.
+
+## Manual smoke tests
+
+Playback:
+
+```bash
+PYTHONPATH=src python examples/play_tone.py
+```
+
+Capture:
+
+```bash
+PYTHONPATH=src python examples/capture_level.py
+```
+
+## Contribution rules
+
+- Keep the public Python API compatible with Python 3.10.
+- Keep native audio callbacks free of Python calls.
+- Add or update tests for behavior changes.
+- Keep platform-specific backend behavior behind the backend protocol.
+- Avoid new runtime dependencies unless they materially improve correctness or
+  packaging.
+
+## Pull request checklist
+
+- Unit tests pass locally.
+- Relevant examples still run when the change affects audio behavior.
+- README/docs are updated for public API changes.
+- Native code handles allocation and shutdown failures explicitly.
+

tachyaudio-0.2.0b1/LICENSE

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

tachyaudio-0.2.0b1/MANIFEST.in

@@ -0,0 +1,14 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CONTRIBUTING.md
+include pyproject.toml
+include setup.py
+recursive-include src/tachyaudio *.c *.h *.LICENSE *.md *.py py.typed
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include tests *.py
+recursive-include .github/workflows *.yml
+global-exclude __pycache__/*
+global-exclude *.py[cod]
+global-exclude .DS_Store

tachyaudio-0.2.0b1/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: tachyaudio
+Version: 0.2.0b1
+Summary: Low-level audio primitives for tachypy and Python experiments.
+Author: tachyaudio contributors
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+# tachyaudio
+
+`tachyaudio` is a low-level audio package intended to replace tachypy’s direct
+dependency on `sounddevice`/PortAudio over time.
+
+Status: beta. The native backend currently supports macOS through Core Audio and
+Linux through vendored `miniaudio`. Windows support is planned but intentionally
+deferred until Windows test hardware is available.
+
+## Goals
+
+- install from `pip` without requiring users to install PortAudio separately
+- keep real-time audio work out of Python callbacks where possible
+- expose explicit latency, underrun, and overrun diagnostics
+- support playback, capture, duplex streams, and device enumeration
+- keep tachypy’s public API stable while the backend evolves
+
+## Non-goals
+
+- full DAW-style audio graph support in the initial release
+- replacing OS audio stacks such as Core Audio, WASAPI, ALSA, or PulseAudio
+- exposing backend-specific details as the primary user API
+
+## Initial API shape
+
+```python
+import tachyaudio as ta
+
+devices = ta.list_devices()
+
+stream = ta.OutputStream(sample_rate=48_000, channels=2)
+stream.write(samples)
+with stream:
+    ...
+
+stats = ta.play(samples, sample_rate=48_000, channels=2)
+```
+
+The native backend currently supports device enumeration, float32 output
+playback, and nonblocking float32 input capture on macOS and Linux.
+
+`OutputStream` is currently a continuous stream. Write audio before or during
+playback; if the stream runs out of queued frames it outputs silence and counts
+an underrun.
+
+Use `tachyaudio.play()` for finite stimuli that should start, drain, and close
+as a single operation.
+
+See `examples/play_wav.py` for dependency-free playback of WAV files exported
+from an editor such as Audacity. The repository example uses a 48 kHz float WAV
+to avoid runtime resampling. Pass `--eq` to show a lightweight five-band
+terminal meter during playback.
+
+Use blocking helpers when callers need complete buffer transfer:
+
+- `OutputStream.write_all(frames, timeout=None)`: wait until all frames are
+  accepted by the output ring
+- `InputStream.read_exactly(frame_count, timeout=None)`: wait until exactly the
+  requested number of frames has been captured
+
+Full-duplex capture/playback is exposed as `DuplexStream`. Native macOS and
+Linux support is available.
+
+Lifecycle semantics:
+
+- `stop()`: stop playback without discarding queued frames
+- `drain()`: wait for queued frames to play
+- `flush()`: discard queued frames without closing the stream
+- `close()`: stop playback and release native resources
+
+`StreamStats` reports:
+
+- `frames_processed`: frames consumed by the backend
+- `underruns` / `overruns`: buffer starvation or rejected writes
+- `hardware_latency`: backend-reported device latency in seconds when available
+- `queued_frames`: frames currently waiting in the native ring
+- `queued_latency`: queued ring duration in seconds
+- `estimated_latency`: `queued_latency + hardware_latency` when hardware latency
+  is available, otherwise queued latency
+- `buffer_size`: native callback buffer size in frames
+
+## Development
+
+Supported Python versions:
+
+- Python 3.10
+- Python 3.11
+- Python 3.12
+- Python 3.13
+- Python 3.14
+
+Run the standard-library test suite:
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+Play a short test tone:
+
+```bash
+PYTHONPATH=src python3 examples/play_tone.py
+```
+
+Capture a short input buffer and print its RMS level:
+
+```bash
+PYTHONPATH=src python3 examples/capture_level.py
+```
+
+`InputStream.read(frame_count)` is nonblocking and returns currently available
+frames up to `frame_count`.
+
+On macOS, a restricted sandbox may hide Core Audio devices. On Linux, sandboxed
+processes may be unable to reach the user PipeWire/PulseAudio server. If
+`tachyaudio.list_devices()` returns an empty tuple or only generic ALSA devices
+in a sandboxed environment, verify from an unsandboxed terminal before debugging
+the backend. Headless Linux containers may return no devices while still being
+able to build and import the native extension.

tachyaudio-0.2.0b1/README.md

@@ -0,0 +1,118 @@
+# tachyaudio
+
+`tachyaudio` is a low-level audio package intended to replace tachypy’s direct
+dependency on `sounddevice`/PortAudio over time.
+
+Status: beta. The native backend currently supports macOS through Core Audio and
+Linux through vendored `miniaudio`. Windows support is planned but intentionally
+deferred until Windows test hardware is available.
+
+## Goals
+
+- install from `pip` without requiring users to install PortAudio separately
+- keep real-time audio work out of Python callbacks where possible
+- expose explicit latency, underrun, and overrun diagnostics
+- support playback, capture, duplex streams, and device enumeration
+- keep tachypy’s public API stable while the backend evolves
+
+## Non-goals
+
+- full DAW-style audio graph support in the initial release
+- replacing OS audio stacks such as Core Audio, WASAPI, ALSA, or PulseAudio
+- exposing backend-specific details as the primary user API
+
+## Initial API shape
+
+```python
+import tachyaudio as ta
+
+devices = ta.list_devices()
+
+stream = ta.OutputStream(sample_rate=48_000, channels=2)
+stream.write(samples)
+with stream:
+    ...
+
+stats = ta.play(samples, sample_rate=48_000, channels=2)
+```
+
+The native backend currently supports device enumeration, float32 output
+playback, and nonblocking float32 input capture on macOS and Linux.
+
+`OutputStream` is currently a continuous stream. Write audio before or during
+playback; if the stream runs out of queued frames it outputs silence and counts
+an underrun.
+
+Use `tachyaudio.play()` for finite stimuli that should start, drain, and close
+as a single operation.
+
+See `examples/play_wav.py` for dependency-free playback of WAV files exported
+from an editor such as Audacity. The repository example uses a 48 kHz float WAV
+to avoid runtime resampling. Pass `--eq` to show a lightweight five-band
+terminal meter during playback.
+
+Use blocking helpers when callers need complete buffer transfer:
+
+- `OutputStream.write_all(frames, timeout=None)`: wait until all frames are
+  accepted by the output ring
+- `InputStream.read_exactly(frame_count, timeout=None)`: wait until exactly the
+  requested number of frames has been captured
+
+Full-duplex capture/playback is exposed as `DuplexStream`. Native macOS and
+Linux support is available.
+
+Lifecycle semantics:
+
+- `stop()`: stop playback without discarding queued frames
+- `drain()`: wait for queued frames to play
+- `flush()`: discard queued frames without closing the stream
+- `close()`: stop playback and release native resources
+
+`StreamStats` reports:
+
+- `frames_processed`: frames consumed by the backend
+- `underruns` / `overruns`: buffer starvation or rejected writes
+- `hardware_latency`: backend-reported device latency in seconds when available
+- `queued_frames`: frames currently waiting in the native ring
+- `queued_latency`: queued ring duration in seconds
+- `estimated_latency`: `queued_latency + hardware_latency` when hardware latency
+  is available, otherwise queued latency
+- `buffer_size`: native callback buffer size in frames
+
+## Development
+
+Supported Python versions:
+
+- Python 3.10
+- Python 3.11
+- Python 3.12
+- Python 3.13
+- Python 3.14
+
+Run the standard-library test suite:
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+Play a short test tone:
+
+```bash
+PYTHONPATH=src python3 examples/play_tone.py
+```
+
+Capture a short input buffer and print its RMS level:
+
+```bash
+PYTHONPATH=src python3 examples/capture_level.py
+```
+
+`InputStream.read(frame_count)` is nonblocking and returns currently available
+frames up to `frame_count`.
+
+On macOS, a restricted sandbox may hide Core Audio devices. On Linux, sandboxed
+processes may be unable to reach the user PipeWire/PulseAudio server. If
+`tachyaudio.list_devices()` returns an empty tuple or only generic ALSA devices
+in a sandboxed environment, verify from an unsandboxed terminal before debugging
+the backend. Headless Linux containers may return no devices while still being
+able to build and import the native extension.

tachyaudio-0.2.0b1/docs/architecture.md

@@ -0,0 +1,100 @@
+# tachyaudio architecture
+
+## Package boundary
+
+`tachyaudio` owns low-level audio primitives. `tachypy` should not depend on
+backend-specific concepts directly. Instead, tachypy should wrap `tachyaudio`
+from `tachypy.audio` and provide experiment-oriented scheduling, stimulus
+construction, and compatibility behavior.
+
+## Backend boundary
+
+The public Python API delegates to an internal backend protocol:
+
+- `list_devices()`
+- `open_output_stream(config)`
+- `open_input_stream(config)`
+
+The first production backend should be native. The current first slices expose
+macOS Core Audio device enumeration and output playback directly so the build
+and Python boundary can be validated. Playback uses preallocated Core Audio
+queue buffers fed by a native ring buffer. A future cross-platform
+implementation can move to vendored `miniaudio` once the desired callback,
+buffering, and drain semantics are clearer.
+
+Finite playback uses an explicit drain mode: partial final buffers are padded
+with silence without counting as underruns, and callbacks stop refilling once
+queued audio has drained.
+
+Stream lifecycle methods have distinct responsibilities: `stop()` halts playback,
+`drain()` waits for queued audio to finish, `flush()` discards queued ring-buffer
+audio, and `close()` releases native resources.
+
+Input capture mirrors output buffering in reverse: Core Audio callbacks write
+captured float32 frames into a native ring buffer, and Python reads available
+frames without invoking Python from the audio callback.
+
+The core stream methods remain nonblocking: `write()` accepts as many frames as
+the output ring can hold, and `read()` returns currently available captured
+frames. Blocking helpers (`write_all()` and `read_exactly()`) are Python-level
+conveniences layered on top of those primitives.
+
+Full-duplex support is modeled as a backend-level `DuplexStream`, not as a
+Python wrapper around one `OutputStream` and one `InputStream`. Backends should
+use a single native duplex callback where available so capture and playback share
+one scheduling clock. The current macOS implementation owns both native Core
+Audio queues inside one native stream object. The Linux miniaudio implementation
+uses one native duplex device callback.
+
+Stream statistics distinguish queue state from hardware behavior. `queued_frames`
+and `queued_latency` describe the native ring buffer. `hardware_latency`
+describes backend-reported device latency when available. `buffer_size`
+describes the callback buffer size in frames. `estimated_latency` reports
+`queued_latency + hardware_latency` when hardware latency is available, otherwise
+queued latency.
+
+## Real-time constraints
+
+Audio callbacks must not call Python. Native backend code should own:
+
+- device callback execution
+- ring-buffer reads and writes
+- underrun and overrun counters
+- format conversion when needed
+- stream start/stop synchronization
+
+Python should submit buffers, inspect diagnostics, and control stream lifecycle.
+
+## Packaging strategy
+
+Support CPython 3.10 through 3.14. Keep the Python layer syntax-compatible with
+3.10, and build wheels for each supported CPython minor version because native
+extension modules are ABI-specific unless we intentionally move to the stable
+ABI.
+
+Ship wheels for supported platforms:
+
+- macOS arm64/x86_64 using Core Audio
+- Windows x86_64/arm64 using WASAPI
+- Linux x86_64/aarch64 using the best available runtime backend
+
+Source builds should remain possible, but routine users should not need to
+install PortAudio or a compiler.
+
+## Native backend milestone
+
+The minimum useful native backend is:
+
+1. device enumeration
+2. output stream
+3. input stream
+4. frame counters
+5. underrun/overrun counters
+6. explicit latency configuration
+7. wheel builds in CI
+
+## macOS sandbox note
+
+Core Audio device enumeration can return zero devices when run from a restricted
+sandbox, even when the host Mac has audio hardware. Validate native enumeration
+from an unsandboxed process before treating an empty list as a backend defect.

tachyaudio-0.2.0b1/docs/python-support.md

@@ -0,0 +1,36 @@
+# Python support policy
+
+`tachyaudio` targets CPython 3.10 through 3.14.
+
+## Compatibility rules
+
+- Keep public Python code syntax-compatible with Python 3.10.
+- Avoid runtime dependencies unless they materially improve packaging or audio
+  correctness.
+- Build and test native wheels for every supported CPython minor version.
+- Treat Python 3.10 as the lower-bound type-checking target.
+- Add version-specific code only behind narrow compatibility helpers.
+
+## Wheel targets and ABI decision
+
+Initial wheel scope:
+
+- `cp310`
+- `cp311`
+- `cp312`
+- `cp313`
+- `cp314`
+
+The native extension currently uses the regular CPython C API. That means wheel
+builds are per-CPython-version. Moving to Python’s stable ABI can be evaluated
+later, but only after the native API settles.
+
+For the public beta, `tachyaudio` intentionally ships per-version CPython
+wheels (`cp310` through `cp314`) rather than `abi3` wheels. This keeps the
+native backend implementation unconstrained while macOS and Linux playback,
+capture, duplex streams, and diagnostics are still evolving. The additional
+wheel matrix is acceptable because cibuildwheel already builds the supported
+Python minors explicitly.
+
+CI should run unit tests on every supported Python minor version before a wheel
+is published.