openbeats 0.1.0__tar.gz

openbeats-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+checkpoints/
+*.npz
+dist/
+.pytest_cache/

openbeats-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: openbeats
+Version: 0.1.0
+Summary: Inference for the OpenBEATs audio encoder (vendored ESPnet BeatsEncoder)
+Project-URL: Homepage, https://shikhar-s.github.io/OpenBEATs/
+Project-URL: Paper, https://arxiv.org/abs/2507.14129
+Author: Shikhar Bharadwaj
+License-Expression: MIT
+Keywords: audio,beats,bioacoustics,embeddings,espnet,openbeats
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: huggingface-hub
+Requires-Dist: numpy
+Requires-Dist: packaging
+Requires-Dist: pyyaml
+Requires-Dist: soundfile
+Requires-Dist: torch>=2.0
+Requires-Dist: torchaudio>=2.0
+Provides-Extra: adapter
+Requires-Dist: transformers; extra == 'adapter'
+Description-Content-Type: text/markdown
+
+# OpenBEATs inference
+
+Run inference with [OpenBEATs](https://shikhar-s.github.io/OpenBEATs/), a
+general-purpose audio encoder pre-trained on speech, music, environmental sound,
+and bioacoustics ([paper](https://arxiv.org/abs/2507.14129)). Given an audio
+file, it produces patch-level embeddings.
+
+## Install
+
+```bash
+pip install openbeats
+```
+
+This installs the `openbeats-infer` / `openbeats-download` commands. Dependencies
+are kept lean (torch, torchaudio, numpy, huggingface-hub, pyyaml, soundfile) and
+declared with lower bounds, so an existing torch install is reused rather than
+reinstalled. For a fully isolated CLI that doesn't touch your environment, use
+[`uv tool`](https://docs.astral.sh/uv/) or `pipx`:
+
+```bash
+uv tool install openbeats     # or: pipx install openbeats
+```
+
+## Usage
+
+### CLI — quick prototyping
+
+```bash
+openbeats-infer --checkpoint espnet/OpenBEATS-Large-i1-as20k \
+    --audio your_audio.wav --out embeddings.npz
+```
+
+`--checkpoint` accepts a Hugging Face repo id (auto-downloaded), a local
+directory, or a checkpoint file. The `.npz` holds `patch_embeddings`
+`(num_patches, 1024)` (plus `logits`/`probs` for classification checkpoints).
+Options: `--device cuda`, `--max-layer N`, `--chunk-seconds 10` (long audio).
+
+### Python — from an audio file
+
+```python
+from openbeats.model import OpenBeats
+
+model = OpenBeats.from_pretrained("espnet/OpenBEATS-Large-i1-as20k", device="cuda")
+out = model.encode_file("your_audio.wav")          # or chunk_seconds=10 for long audio
+print(out["patch_embeddings"].shape)               # (num_patches, 1024)
+```
+
+### Python — from your own waveform
+
+Pass a 1-D 16 kHz waveform in `[-1, 1]` (use `load_audio` for other rates):
+
+```python
+import numpy as np
+from openbeats.utils import load_audio
+
+wav, sr = load_audio("your_audio.wav")             # any rate -> mono 16 kHz
+out = model.encode(wav, sr)                         # or pass your own np.ndarray
+print(out["patch_embeddings"].shape)               # (num_patches, 1024)
+```
+
+## Checkpoints
+
+Browse variants (Base/Large, AudioSet and bioacoustics fine-tunes) in the
+[espnet OpenBEATs collection](https://huggingface.co/collections/espnet/openbeats).
+
+## Development
+
+```bash
+uv sync                       # install with dev deps (pytest)
+uv run pytest                 # unit tests (no downloads)
+OPENBEATS_INTEGRATION=1 uv run pytest   # + end-to-end (downloads from HF)
+uv build                      # build wheel + sdist into dist/
+uv publish                    # publish to PyPI
+```

openbeats-0.1.0/README.md

@@ -0,0 +1,74 @@
+# OpenBEATs inference
+
+Run inference with [OpenBEATs](https://shikhar-s.github.io/OpenBEATs/), a
+general-purpose audio encoder pre-trained on speech, music, environmental sound,
+and bioacoustics ([paper](https://arxiv.org/abs/2507.14129)). Given an audio
+file, it produces patch-level embeddings.
+
+## Install
+
+```bash
+pip install openbeats
+```
+
+This installs the `openbeats-infer` / `openbeats-download` commands. Dependencies
+are kept lean (torch, torchaudio, numpy, huggingface-hub, pyyaml, soundfile) and
+declared with lower bounds, so an existing torch install is reused rather than
+reinstalled. For a fully isolated CLI that doesn't touch your environment, use
+[`uv tool`](https://docs.astral.sh/uv/) or `pipx`:
+
+```bash
+uv tool install openbeats     # or: pipx install openbeats
+```
+
+## Usage
+
+### CLI — quick prototyping
+
+```bash
+openbeats-infer --checkpoint espnet/OpenBEATS-Large-i1-as20k \
+    --audio your_audio.wav --out embeddings.npz
+```
+
+`--checkpoint` accepts a Hugging Face repo id (auto-downloaded), a local
+directory, or a checkpoint file. The `.npz` holds `patch_embeddings`
+`(num_patches, 1024)` (plus `logits`/`probs` for classification checkpoints).
+Options: `--device cuda`, `--max-layer N`, `--chunk-seconds 10` (long audio).
+
+### Python — from an audio file
+
+```python
+from openbeats.model import OpenBeats
+
+model = OpenBeats.from_pretrained("espnet/OpenBEATS-Large-i1-as20k", device="cuda")
+out = model.encode_file("your_audio.wav")          # or chunk_seconds=10 for long audio
+print(out["patch_embeddings"].shape)               # (num_patches, 1024)
+```
+
+### Python — from your own waveform
+
+Pass a 1-D 16 kHz waveform in `[-1, 1]` (use `load_audio` for other rates):
+
+```python
+import numpy as np
+from openbeats.utils import load_audio
+
+wav, sr = load_audio("your_audio.wav")             # any rate -> mono 16 kHz
+out = model.encode(wav, sr)                         # or pass your own np.ndarray
+print(out["patch_embeddings"].shape)               # (num_patches, 1024)
+```
+
+## Checkpoints
+
+Browse variants (Base/Large, AudioSet and bioacoustics fine-tunes) in the
+[espnet OpenBEATs collection](https://huggingface.co/collections/espnet/openbeats).
+
+## Development
+
+```bash
+uv sync                       # install with dev deps (pytest)
+uv run pytest                 # unit tests (no downloads)
+OPENBEATS_INTEGRATION=1 uv run pytest   # + end-to-end (downloads from HF)
+uv build                      # build wheel + sdist into dist/
+uv publish                    # publish to PyPI
+```

openbeats-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "openbeats"
+version = "0.1.0"
+description = "Inference for the OpenBEATs audio encoder (vendored ESPnet BeatsEncoder)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Shikhar Bharadwaj" }]
+keywords = ["audio", "beats", "openbeats", "embeddings", "bioacoustics", "espnet"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Sound/Audio :: Analysis",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+# Lower bounds only: an existing torch/torchaudio install satisfies these, so pip
+# won't reinstall and clobber a user's (e.g. CUDA-matched) build.
+dependencies = [
+    "torch>=2.0",
+    "torchaudio>=2.0",
+    "numpy",
+    "packaging",
+    "pyyaml",
+    "huggingface-hub",
+    "soundfile",
+]
+
+[project.optional-dependencies]
+# Only for checkpoints using the wav2vec2 conformer adapter / learned positional
+# embeddings (not used by the standard OpenBEATs encoders).
+adapter = ["transformers"]
+
+[project.scripts]
+openbeats-infer = "openbeats.cli:infer_main"
+openbeats-download = "openbeats.cli:download_main"
+
+[project.urls]
+Homepage = "https://shikhar-s.github.io/OpenBEATs/"
+Paper = "https://arxiv.org/abs/2507.14129"
+
+[dependency-groups]
+dev = ["pytest"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openbeats"]