opuscodec 0.1.2__tar.gz

opuscodec-0.1.2/LICENSE

@@ -0,0 +1,162 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the
+copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other
+entities that control, are controlled by, or are under common control with
+that entity. For the purposes of this definition, "control" means (i) the
+power, direct or indirect, to cause the direction or management of such
+entity, whether by contract or otherwise, or (ii) ownership of fifty percent
+(50%) or more of the outstanding shares, or (iii) beneficial ownership of
+such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation source, and
+configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object
+code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work (an example is provided in the Appendix
+below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form,
+that is based on (or derived from) the Work and for which the editorial
+revisions, annotations, elaborations, or other modifications represent, as a
+whole, an original work of authorship. For the purposes of this License,
+Derivative Works shall not include works that remain separable from, or
+merely link (or bind by name) to the interfaces of, the Work and Derivative
+Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original
+version of the Work and any modifications or additions to that Work or
+Derivative Works thereof, that is intentionally submitted to Licensor for
+inclusion in the Work by the copyright owner or by an individual or Legal
+Entity authorized to submit on behalf of the copyright owner. For the
+purposes of this definition, "submitted" means any form of electronic, verbal,
+or written communication sent to the Licensor or its representatives,
+including but not limited to communication on electronic mailing lists, source
+code control systems, and issue tracking systems that are managed by, or on
+behalf of, the Licensor for the purpose of discussing and improving the Work,
+but excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
+section) patent license to make, have made, use, offer to sell, sell, import,
+and otherwise transfer the Work, where such license applies only to those
+patent claims licensable by such Contributor that are necessarily infringed by
+their Contribution(s) alone or by combination of their Contribution(s) with
+the Work to which such Contribution(s) was submitted. If You institute patent
+litigation against any entity (including a cross-claim or counterclaim in a
+lawsuit) alleging that the Work or a Contribution incorporated within the Work
+constitutes direct or contributory patent infringement, then any patent
+licenses granted to You under this License for that Work shall terminate as of
+the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy
+of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any
+part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution,
+then any Derivative Works that You distribute must include a readable copy of
+the attribution notices contained within such NOTICE file, excluding those
+notices that do not pertain to any part of the Derivative Works, in at least
+one of the following places: within a NOTICE text file distributed as part of
+the Derivative Works; within the Source form or documentation, if provided
+along with the Derivative Works; or, within a display generated by the
+Derivative Works, if and wherever such third-party notices normally appear.
+The contents of the NOTICE file are for informational purposes only and do not
+modify the License. You may add Your own attribution notices within Derivative
+Works that You distribute, alongside or as an addendum to the NOTICE text from
+the Work, provided that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a
+whole, provided Your use, reproduction, and distribution of the Work otherwise
+complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein
+shall supersede or modify the terms of any separate license agreement you may
+have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as
+required for reasonable and customary use in describing the origin of the Work
+and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties
+or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any
+character arising as a result of this License or out of the use or inability to
+use the Work (including but not limited to damages for loss of goodwill, work
+stoppage, computer failure or malfunction, or any and all other commercial
+damages or losses), even if such Contributor has been advised of the
+possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work
+or Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree
+to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

opuscodec-0.1.2/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: opuscodec
+Version: 0.1.2
+Summary: Python bindings and self-contained Opus CLI builds with QEXT enabled by default.
+Author-email: Fish Audio <lengyue@fish.audio>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/fishaudio/opuscodec
+Project-URL: Repository, https://github.com/fishaudio/opuscodec
+Project-URL: Issues, https://github.com/fishaudio/opuscodec/issues
+Project-URL: Releases, https://github.com/fishaudio/opuscodec/releases
+Keywords: opus,audio,codec,pybind11,qext
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Dynamic: license-file
+
+# opuscodec
+
+Python bindings and self-contained Opus CLI builds, with **QEXT enabled by default**.
+
+`opuscodec` packages three things together:
+
+- `OpusBufferedEncoder` / `OpusBufferedDecoder` Python bindings
+- self-contained `opusenc` / `opusdec` release binaries
+- vendored Xiph dependencies, built from source when needed
+
+Stable dependency set:
+
+- `opus` `1.6.1`
+- `opus-tools` `0.2`
+- `libogg` `1.3.6`
+- `opusfile` `0.12`
+- `libopusenc` `0.3`
+
+## Why this package
+
+- no system Opus install required by default
+- runtime + build-time QEXT control
+- Python API and CLI assets released from one repo
+- PyPI wheels for supported targets, source build fallback everywhere else
+
+## Installation
+
+### PyPI (recommended)
+
+```bash
+python -m pip install opuscodec==0.1.2
+```
+
+### GitHub Release asset
+
+```bash
+python -m pip install "https://github.com/fishaudio/opuscodec/releases/download/v0.1.2/<wheel-file-name>.whl"
+```
+
+Example Linux wheel name:
+
+```bash
+python -m pip install ./opuscodec-0.1.2-cp312-cp312-manylinux_2_28_x86_64.whl
+```
+
+### Source build
+
+```bash
+make test
+```
+
+Common commands:
+
+```bash
+make install    # editable install + test deps
+make test       # run pytest
+make wheel      # build wheel into dist/wheels
+make binaries   # build opusenc/opusdec into dist/bin
+make clean      # clean build artifacts
+```
+
+## Python example
+
+```python
+import numpy as np
+import opuscodec
+
+sr = 48000
+x = (0.1 * np.sin(2 * np.pi * 440 * np.arange(sr) / sr) * 32767).astype(np.int16).reshape(-1, 1)
+
+enc = opuscodec.OpusBufferedEncoder(sample_rate=sr, channels=1)
+packet = enc.write(x) + enc.flush()
+
+dec = opuscodec.OpusBufferedDecoder()
+y = dec.decode(packet)
+
+print(y.shape, opuscodec.opus_version(), opuscodec.qext_enabled(), enc.qext_enabled())
+```
+
+Disable runtime QEXT for one encoder instance:
+
+```python
+enc = opuscodec.OpusBufferedEncoder(sample_rate=48000, channels=1, qext=False)
+```
+
+## Standalone binary usage
+
+After downloading release binaries:
+
+```bash
+tar -xzf opuscodec-v0.1.2-linux-amd64-binaries.tar.gz
+chmod +x opusenc opusdec
+```
+
+### WAV roundtrip
+
+```bash
+./opusenc input.wav output.opus
+./opusdec output.opus roundtrip.wav
+```
+
+`opusenc` enables QEXT by default in this repository build. Disable it explicitly for comparison tests:
+
+```bash
+./opusenc --set-ctl-int 4056=0 input.wav output-noqext.opus
+```
+
+### Raw PCM roundtrip
+
+Encode raw PCM (`mono`, `48k`, `s16le`) to Opus:
+
+```bash
+./opusenc --raw --raw-bits 16 --raw-rate 48000 --raw-chan 1 input.pcm output.opus
+```
+
+Decode Opus back to PCM:
+
+```bash
+./opusdec output.opus decoded.pcm
+```
+
+## Build configuration
+
+Defaults: vendored dependencies; QEXT enabled.
+
+Optional environment variables:
+
+- `OPUSCODEC_ENABLE_QEXT=0` — disable QEXT
+- `OPUSCODEC_USE_SYSTEM_DEPS=1` — use system libraries instead of vendored build
+- `OPUSCODEC_DEPS_PREFIX=/path/to/prefix` — custom dependency prefix
+
+When QEXT is enabled at build time, packaged `opusenc` binaries also enable `OPUS_SET_QEXT(1)` by default.
+
+## Repository layout
+
+```text
+.
+├── .github/workflows/build.yml
+├── Makefile
+├── pyproject.toml
+├── setup.py
+├── src/
+│   └── opuscodec_bindings.cpp
+├── scripts/
+│   ├── build_deps.sh
+│   └── build_binaries.sh
+├── tests/
+│   └── test_bindings.py
+├── opusenc.py
+└── opusdec.py
+```
+
+## Release automation
+
+On tag push (for example `v0.1.2`), GitHub Actions will:
+
+- run tests on Linux + macOS
+- build PyPI-compatible manylinux wheels for Linux
+- build macOS arm64 wheels
+- build an `sdist`
+- publish wheel + sdist artifacts to PyPI via OIDC
+- create a GitHub Release and upload wheels + binary tarballs
+
+## License
+
+Apache License 2.0. See [LICENSE](./LICENSE).

opuscodec-0.1.2/README.md

@@ -0,0 +1,166 @@
+# opuscodec
+
+Python bindings and self-contained Opus CLI builds, with **QEXT enabled by default**.
+
+`opuscodec` packages three things together:
+
+- `OpusBufferedEncoder` / `OpusBufferedDecoder` Python bindings
+- self-contained `opusenc` / `opusdec` release binaries
+- vendored Xiph dependencies, built from source when needed
+
+Stable dependency set:
+
+- `opus` `1.6.1`
+- `opus-tools` `0.2`
+- `libogg` `1.3.6`
+- `opusfile` `0.12`
+- `libopusenc` `0.3`
+
+## Why this package
+
+- no system Opus install required by default
+- runtime + build-time QEXT control
+- Python API and CLI assets released from one repo
+- PyPI wheels for supported targets, source build fallback everywhere else
+
+## Installation
+
+### PyPI (recommended)
+
+```bash
+python -m pip install opuscodec==0.1.2
+```
+
+### GitHub Release asset
+
+```bash
+python -m pip install "https://github.com/fishaudio/opuscodec/releases/download/v0.1.2/<wheel-file-name>.whl"
+```
+
+Example Linux wheel name:
+
+```bash
+python -m pip install ./opuscodec-0.1.2-cp312-cp312-manylinux_2_28_x86_64.whl
+```
+
+### Source build
+
+```bash
+make test
+```
+
+Common commands:
+
+```bash
+make install    # editable install + test deps
+make test       # run pytest
+make wheel      # build wheel into dist/wheels
+make binaries   # build opusenc/opusdec into dist/bin
+make clean      # clean build artifacts
+```
+
+## Python example
+
+```python
+import numpy as np
+import opuscodec
+
+sr = 48000
+x = (0.1 * np.sin(2 * np.pi * 440 * np.arange(sr) / sr) * 32767).astype(np.int16).reshape(-1, 1)
+
+enc = opuscodec.OpusBufferedEncoder(sample_rate=sr, channels=1)
+packet = enc.write(x) + enc.flush()
+
+dec = opuscodec.OpusBufferedDecoder()
+y = dec.decode(packet)
+
+print(y.shape, opuscodec.opus_version(), opuscodec.qext_enabled(), enc.qext_enabled())
+```
+
+Disable runtime QEXT for one encoder instance:
+
+```python
+enc = opuscodec.OpusBufferedEncoder(sample_rate=48000, channels=1, qext=False)
+```
+
+## Standalone binary usage
+
+After downloading release binaries:
+
+```bash
+tar -xzf opuscodec-v0.1.2-linux-amd64-binaries.tar.gz
+chmod +x opusenc opusdec
+```
+
+### WAV roundtrip
+
+```bash
+./opusenc input.wav output.opus
+./opusdec output.opus roundtrip.wav
+```
+
+`opusenc` enables QEXT by default in this repository build. Disable it explicitly for comparison tests:
+
+```bash
+./opusenc --set-ctl-int 4056=0 input.wav output-noqext.opus
+```
+
+### Raw PCM roundtrip
+
+Encode raw PCM (`mono`, `48k`, `s16le`) to Opus:
+
+```bash
+./opusenc --raw --raw-bits 16 --raw-rate 48000 --raw-chan 1 input.pcm output.opus
+```
+
+Decode Opus back to PCM:
+
+```bash
+./opusdec output.opus decoded.pcm
+```
+
+## Build configuration
+
+Defaults: vendored dependencies; QEXT enabled.
+
+Optional environment variables:
+
+- `OPUSCODEC_ENABLE_QEXT=0` — disable QEXT
+- `OPUSCODEC_USE_SYSTEM_DEPS=1` — use system libraries instead of vendored build
+- `OPUSCODEC_DEPS_PREFIX=/path/to/prefix` — custom dependency prefix
+
+When QEXT is enabled at build time, packaged `opusenc` binaries also enable `OPUS_SET_QEXT(1)` by default.
+
+## Repository layout
+
+```text
+.
+├── .github/workflows/build.yml
+├── Makefile
+├── pyproject.toml
+├── setup.py
+├── src/
+│   └── opuscodec_bindings.cpp
+├── scripts/
+│   ├── build_deps.sh
+│   └── build_binaries.sh
+├── tests/
+│   └── test_bindings.py
+├── opusenc.py
+└── opusdec.py
+```
+
+## Release automation
+
+On tag push (for example `v0.1.2`), GitHub Actions will:
+
+- run tests on Linux + macOS
+- build PyPI-compatible manylinux wheels for Linux
+- build macOS arm64 wheels
+- build an `sdist`
+- publish wheel + sdist artifacts to PyPI via OIDC
+- create a GitHub Release and upload wheels + binary tarballs
+
+## License
+
+Apache License 2.0. See [LICENSE](./LICENSE).

opuscodec-0.1.2/opuscodec.egg-info/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: opuscodec
+Version: 0.1.2
+Summary: Python bindings and self-contained Opus CLI builds with QEXT enabled by default.
+Author-email: Fish Audio <lengyue@fish.audio>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/fishaudio/opuscodec
+Project-URL: Repository, https://github.com/fishaudio/opuscodec
+Project-URL: Issues, https://github.com/fishaudio/opuscodec/issues
+Project-URL: Releases, https://github.com/fishaudio/opuscodec/releases
+Keywords: opus,audio,codec,pybind11,qext
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Dynamic: license-file
+
+# opuscodec
+
+Python bindings and self-contained Opus CLI builds, with **QEXT enabled by default**.
+
+`opuscodec` packages three things together:
+
+- `OpusBufferedEncoder` / `OpusBufferedDecoder` Python bindings
+- self-contained `opusenc` / `opusdec` release binaries
+- vendored Xiph dependencies, built from source when needed
+
+Stable dependency set:
+
+- `opus` `1.6.1`
+- `opus-tools` `0.2`
+- `libogg` `1.3.6`
+- `opusfile` `0.12`
+- `libopusenc` `0.3`
+
+## Why this package
+
+- no system Opus install required by default
+- runtime + build-time QEXT control
+- Python API and CLI assets released from one repo
+- PyPI wheels for supported targets, source build fallback everywhere else
+
+## Installation
+
+### PyPI (recommended)
+
+```bash
+python -m pip install opuscodec==0.1.2
+```
+
+### GitHub Release asset
+
+```bash
+python -m pip install "https://github.com/fishaudio/opuscodec/releases/download/v0.1.2/<wheel-file-name>.whl"
+```
+
+Example Linux wheel name:
+
+```bash
+python -m pip install ./opuscodec-0.1.2-cp312-cp312-manylinux_2_28_x86_64.whl
+```
+
+### Source build
+
+```bash
+make test
+```
+
+Common commands:
+
+```bash
+make install    # editable install + test deps
+make test       # run pytest
+make wheel      # build wheel into dist/wheels
+make binaries   # build opusenc/opusdec into dist/bin
+make clean      # clean build artifacts
+```
+
+## Python example
+
+```python
+import numpy as np
+import opuscodec
+
+sr = 48000
+x = (0.1 * np.sin(2 * np.pi * 440 * np.arange(sr) / sr) * 32767).astype(np.int16).reshape(-1, 1)
+
+enc = opuscodec.OpusBufferedEncoder(sample_rate=sr, channels=1)
+packet = enc.write(x) + enc.flush()
+
+dec = opuscodec.OpusBufferedDecoder()
+y = dec.decode(packet)
+
+print(y.shape, opuscodec.opus_version(), opuscodec.qext_enabled(), enc.qext_enabled())
+```
+
+Disable runtime QEXT for one encoder instance:
+
+```python
+enc = opuscodec.OpusBufferedEncoder(sample_rate=48000, channels=1, qext=False)
+```
+
+## Standalone binary usage
+
+After downloading release binaries:
+
+```bash
+tar -xzf opuscodec-v0.1.2-linux-amd64-binaries.tar.gz
+chmod +x opusenc opusdec
+```
+
+### WAV roundtrip
+
+```bash
+./opusenc input.wav output.opus
+./opusdec output.opus roundtrip.wav
+```
+
+`opusenc` enables QEXT by default in this repository build. Disable it explicitly for comparison tests:
+
+```bash
+./opusenc --set-ctl-int 4056=0 input.wav output-noqext.opus
+```
+
+### Raw PCM roundtrip
+
+Encode raw PCM (`mono`, `48k`, `s16le`) to Opus:
+
+```bash
+./opusenc --raw --raw-bits 16 --raw-rate 48000 --raw-chan 1 input.pcm output.opus
+```
+
+Decode Opus back to PCM:
+
+```bash
+./opusdec output.opus decoded.pcm
+```
+
+## Build configuration
+
+Defaults: vendored dependencies; QEXT enabled.
+
+Optional environment variables:
+
+- `OPUSCODEC_ENABLE_QEXT=0` — disable QEXT
+- `OPUSCODEC_USE_SYSTEM_DEPS=1` — use system libraries instead of vendored build
+- `OPUSCODEC_DEPS_PREFIX=/path/to/prefix` — custom dependency prefix
+
+When QEXT is enabled at build time, packaged `opusenc` binaries also enable `OPUS_SET_QEXT(1)` by default.
+
+## Repository layout
+
+```text
+.
+├── .github/workflows/build.yml
+├── Makefile
+├── pyproject.toml
+├── setup.py
+├── src/
+│   └── opuscodec_bindings.cpp
+├── scripts/
+│   ├── build_deps.sh
+│   └── build_binaries.sh
+├── tests/
+│   └── test_bindings.py
+├── opusenc.py
+└── opusdec.py
+```
+
+## Release automation
+
+On tag push (for example `v0.1.2`), GitHub Actions will:
+
+- run tests on Linux + macOS
+- build PyPI-compatible manylinux wheels for Linux
+- build macOS arm64 wheels
+- build an `sdist`
+- publish wheel + sdist artifacts to PyPI via OIDC
+- create a GitHub Release and upload wheels + binary tarballs
+
+## License
+
+Apache License 2.0. See [LICENSE](./LICENSE).

opuscodec-0.1.2/opuscodec.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+opusdec.py
+opusenc.py
+pyproject.toml
+setup.py
+opuscodec.egg-info/PKG-INFO
+opuscodec.egg-info/SOURCES.txt
+opuscodec.egg-info/dependency_links.txt
+opuscodec.egg-info/not-zip-safe
+opuscodec.egg-info/requires.txt
+opuscodec.egg-info/top_level.txt
+src/opuscodec_bindings.cpp
+tests/test_bindings.py

opuscodec-0.1.2/opuscodec.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

opuscodec-0.1.2/opuscodec.egg-info/not-zip-safe

@@ -0,0 +1 @@
+

opuscodec-0.1.2/opuscodec.egg-info/requires.txt

@@ -0,0 +1,4 @@
+numpy>=1.24
+
+[test]
+pytest>=8.0

opuscodec-0.1.2/opuscodec.egg-info/top_level.txt

@@ -0,0 +1,3 @@
+opuscodec
+opusdec
+opusenc

opuscodec-0.1.2/opusdec.py

@@ -0,0 +1,5 @@
+"""Compatibility wrapper for the Opus decoder binding."""
+
+from opuscodec import OpusBufferedDecoder
+
+__all__ = ["OpusBufferedDecoder"]

opuscodec-0.1.2/opusenc.py

@@ -0,0 +1,5 @@
+"""Compatibility wrapper for the Opus encoder binding."""
+
+from opuscodec import OpusBufferedEncoder
+
+__all__ = ["OpusBufferedEncoder"]

opuscodec-0.1.2/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = [
+    "setuptools>=77",
+    "wheel",
+    "pybind11>=2.11",
+    "numpy>=1.24",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "opuscodec"
+version = "0.1.2"
+description = "Python bindings and self-contained Opus CLI builds with QEXT enabled by default."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Fish Audio", email = "lengyue@fish.audio" },
+]
+keywords = ["opus", "audio", "codec", "pybind11", "qext"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: C++",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "numpy>=1.24",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/fishaudio/opuscodec"
+Repository = "https://github.com/fishaudio/opuscodec"
+Issues = "https://github.com/fishaudio/opuscodec/issues"
+Releases = "https://github.com/fishaudio/opuscodec/releases"
+
+[tool.setuptools]
+py-modules = ["opusenc", "opusdec"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py39"
+
+[tool.ruff.lint]
+extend-select = [
+    "B",
+    "I",
+    "PGH",
+    "RUF",
+    "UP",
+]

opuscodec-0.1.2/setup.cfg

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

opuscodec-0.1.2/setup.py

@@ -0,0 +1,74 @@
+import os
+import platform
+import re
+import subprocess
+from pathlib import Path
+
+from pybind11.setup_helpers import Pybind11Extension, build_ext
+from setuptools import setup
+
+ROOT = Path(__file__).resolve().parent
+
+
+def read_project_version() -> str:
+    pyproject = (ROOT / "pyproject.toml").read_text(encoding="utf-8")
+    match = re.search(r'^version\s*=\s*"([^"]+)"\s*$', pyproject, re.MULTILINE)
+    if not match:
+        raise RuntimeError("Could not determine package version from pyproject.toml")
+    return match.group(1)
+
+
+__version__ = read_project_version()
+
+
+class OpusCodecBuildExt(build_ext):
+    def build_extensions(self):
+        use_system_deps = os.environ.get("OPUSCODEC_USE_SYSTEM_DEPS", "0") == "1"
+        qext_requested = os.environ.get("OPUSCODEC_ENABLE_QEXT", "1") != "0"
+
+        include_dirs = []
+        library_dirs = []
+        qext_enabled = qext_requested
+
+        if not use_system_deps:
+            platform_tag = f"{platform.system().lower()}-{platform.machine().lower()}"
+            deps_prefix = Path(
+                os.environ.get("OPUSCODEC_DEPS_PREFIX", ROOT / "build" / "deps" / platform_tag)
+            ).resolve()
+            build_script = ROOT / "scripts" / "build_deps.sh"
+            env = os.environ.copy()
+            env.setdefault("OPUSCODEC_ENABLE_QEXT", "1" if qext_requested else "0")
+            env.setdefault("OPUSCODEC_WITH_OPUS_TOOLS", "0")
+            subprocess.check_call(["bash", str(build_script), str(deps_prefix)], cwd=ROOT, env=env)
+            include_dirs.append(str(deps_prefix / "include"))
+            include_dirs.append(str(deps_prefix / "include" / "opus"))
+            library_dirs.append(str(deps_prefix / "lib"))
+            qext_enabled = (deps_prefix / ".qext-enabled").exists()
+
+        libraries = ["opusenc", "opusfile", "opus", "ogg"]
+        if platform.system() == "Linux":
+            libraries.append("m")
+
+        for ext in self.extensions:
+            ext.include_dirs.extend(include_dirs)
+            ext.library_dirs.extend(library_dirs)
+            ext.libraries.extend(libraries)
+            ext.define_macros.append(("OPUSCODEC_QEXT_ENABLED", "1" if qext_enabled else "0"))
+
+        super().build_extensions()
+
+
+ext_modules = [
+    Pybind11Extension(
+        "opuscodec",
+        ["src/opuscodec_bindings.cpp"],
+        define_macros=[("VERSION_INFO", __version__)],
+        cxx_std=17,
+    ),
+]
+
+setup(
+    ext_modules=ext_modules,
+    cmdclass={"build_ext": OpusCodecBuildExt},
+    zip_safe=False,
+)

opuscodec-0.1.2/src/opuscodec_bindings.cpp

@@ -0,0 +1,306 @@
+#include <opus/opus.h>
+#include <opus/opusenc.h>
+#include <opus/opusfile.h>
+
+#include <pybind11/numpy.h>
+#include <pybind11/pybind11.h>
+
+#include <cstdint>
+#include <cstring>
+#include <limits>
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+namespace py = pybind11;
+
+namespace {
+constexpr int kMaxSamplesPerChannel = 120 * 48;
+#if defined(OPUSCODEC_QEXT_ENABLED)
+constexpr bool kQextDefaultEnabled = true;
+#else
+constexpr bool kQextDefaultEnabled = false;
+#endif
+
+[[noreturn]] void throw_value_error(const char *msg) {
+    throw py::value_error(msg);
+}
+
+std::string ope_error_message(int err) {
+    const char *err_str = ope_strerror(err);
+    if (err_str == nullptr) {
+        return "Unknown Opus encoder error";
+    }
+    return std::string(err_str);
+}
+
+}  // namespace
+
+class OpusBufferedEncoder {
+   public:
+    OpusBufferedEncoder(int sample_rate,
+                        int channels,
+                        int bitrate = OPUS_AUTO,
+                        int signal_type = 0,
+                        int encoder_complexity = 10,
+                        int decision_delay = 0,
+                        bool qext = kQextDefaultEnabled)
+        : encoder_(nullptr),
+          comments_(nullptr),
+          channels_(channels),
+          has_written_(false),
+          flushed_(false),
+          qext_enabled_(false) {
+        if (channels < 1 || channels > 8) {
+            throw_value_error("Invalid channels, must be in range [1, 8].");
+        }
+        if ((bitrate < 500 || bitrate > 512000) && bitrate != OPUS_BITRATE_MAX && bitrate != OPUS_AUTO) {
+            throw_value_error("Invalid bitrate, must be between 500 and 512000, OPUS_BITRATE_MAX, or OPUS_AUTO.");
+        }
+        if (sample_rate < 8000 || sample_rate > 48000) {
+            throw_value_error("Invalid sample_rate, must be in range [8000, 48000].");
+        }
+        if (encoder_complexity < 0 || encoder_complexity > 10) {
+            throw_value_error("Invalid encoder_complexity, must be in range [0, 10].");
+        }
+        if (decision_delay < 0) {
+            throw_value_error("Invalid decision_delay, must be >= 0.");
+        }
+
+        int error = OPE_OK;
+        comments_ = ope_comments_create();
+        if (comments_ == nullptr) {
+            throw_value_error("Failed to allocate Opus comments.");
+        }
+
+        encoder_ = ope_encoder_create_pull(comments_, sample_rate, channels, 0, &error);
+        if (error != OPE_OK || encoder_ == nullptr) {
+            close();
+            throw py::value_error(("Failed to create Opus encoder: " + ope_error_message(error)).c_str());
+        }
+
+        if (ope_encoder_ctl(encoder_, OPUS_SET_BITRATE(bitrate)) != OPE_OK) {
+            close();
+            throw_value_error("Could not set bitrate.");
+        }
+
+        opus_int32 opus_signal_type = OPUS_AUTO;
+        switch (signal_type) {
+            case 0:
+                opus_signal_type = OPUS_AUTO;
+                break;
+            case 1:
+                opus_signal_type = OPUS_SIGNAL_MUSIC;
+                break;
+            case 2:
+                opus_signal_type = OPUS_SIGNAL_VOICE;
+                break;
+            default:
+                close();
+                throw_value_error("Invalid signal_type, must be 0 (auto), 1 (music), or 2 (voice).");
+        }
+
+        if (ope_encoder_ctl(encoder_, OPUS_SET_SIGNAL(opus_signal_type)) != OPE_OK) {
+            close();
+            throw_value_error("Could not set signal type.");
+        }
+        if (ope_encoder_ctl(encoder_, OPUS_SET_COMPLEXITY(encoder_complexity)) != OPE_OK) {
+            close();
+            throw_value_error("Could not set encoder complexity.");
+        }
+        if (ope_encoder_ctl(encoder_, OPE_SET_DECISION_DELAY(decision_delay)) != OPE_OK) {
+            close();
+            throw_value_error("Could not set decision delay.");
+        }
+
+#if defined(OPUS_SET_QEXT_REQUEST)
+        if (qext) {
+            if (ope_encoder_ctl(encoder_, OPUS_SET_QEXT(1)) != OPE_OK) {
+                close();
+                throw_value_error("Could not enable QEXT.");
+            }
+        }
+#else
+        if (qext) {
+            close();
+            throw_value_error("QEXT requested but this libopus does not expose OPUS_SET_QEXT.");
+        }
+#endif
+
+#if defined(OPUS_GET_QEXT_REQUEST)
+        opus_int32 qext_value = 0;
+        const int qext_ret = ope_encoder_ctl(encoder_, OPUS_GET_QEXT(&qext_value));
+        if (qext_ret == OPE_OK) {
+            qext_enabled_ = (qext_value != 0);
+        } else {
+            qext_enabled_ = false;
+        }
+#else
+        qext_enabled_ = false;
+#endif
+    }
+
+    py::bytes write(const py::array_t<int16_t, py::array::c_style | py::array::forcecast> &buffer) {
+        ensure_open();
+        if (flushed_) {
+            throw_value_error("flush() was already called; create a new encoder instance.");
+        }
+        if (buffer.ndim() != 2 || buffer.shape(1) != channels_) {
+            throw_value_error("Buffer must have shape [samples, channels] matching constructor channels.");
+        }
+        if (buffer.shape(0) == 0) {
+            return py::bytes();
+        }
+
+        const int16_t *data = buffer.data();
+        const auto samples = static_cast<int>(buffer.shape(0));
+        const int ret = ope_encoder_write(encoder_, data, samples);
+        if (ret != OPE_OK) {
+            throw py::value_error(("Encoding failed: " + ope_error_message(ret)).c_str());
+        }
+
+        std::vector<unsigned char> encoded_data;
+        unsigned char *packet = nullptr;
+        opus_int32 len = 0;
+        while (ope_encoder_get_page(encoder_, &packet, &len, 1) != 0) {
+            encoded_data.insert(encoded_data.end(), packet, packet + len);
+            has_written_ = true;
+        }
+
+        return py::bytes(reinterpret_cast<const char *>(encoded_data.data()), encoded_data.size());
+    }
+
+    py::bytes flush() {
+        ensure_open();
+        if (!has_written_) {
+            throw_value_error("You must call write() at least once before flush().");
+        }
+        if (flushed_) {
+            throw_value_error("flush() can only be called once.");
+        }
+
+        const int ret = ope_encoder_drain(encoder_);
+        if (ret != OPE_OK) {
+            throw py::value_error(("Draining failed: " + ope_error_message(ret)).c_str());
+        }
+
+        std::vector<unsigned char> encoded_data;
+        unsigned char *packet = nullptr;
+        opus_int32 len = 0;
+        while (ope_encoder_get_page(encoder_, &packet, &len, 1) != 0) {
+            encoded_data.insert(encoded_data.end(), packet, packet + len);
+        }
+        flushed_ = true;
+        return py::bytes(reinterpret_cast<const char *>(encoded_data.data()), encoded_data.size());
+    }
+
+    void close() {
+        if (encoder_ != nullptr) {
+            ope_encoder_destroy(encoder_);
+            encoder_ = nullptr;
+        }
+        if (comments_ != nullptr) {
+            ope_comments_destroy(comments_);
+            comments_ = nullptr;
+        }
+    }
+
+    bool qext_enabled() const { return qext_enabled_; }
+
+    ~OpusBufferedEncoder() { close(); }
+
+   private:
+    void ensure_open() const {
+        if (encoder_ == nullptr) {
+            throw_value_error("Encoder is closed.");
+        }
+    }
+
+    OggOpusEnc *encoder_;
+    OggOpusComments *comments_;
+    int channels_;
+    bool has_written_;
+    bool flushed_;
+    bool qext_enabled_;
+};
+
+class OpusBufferedDecoder {
+   public:
+    OpusBufferedDecoder() = default;
+
+    py::array_t<int16_t> decode(const py::bytes &opus_data) const {
+        std::string encoded = opus_data;
+        if (encoded.empty()) {
+            return py::array_t<int16_t>(py::array::ShapeContainer{0, 0});
+        }
+        if (encoded.size() > static_cast<size_t>(std::numeric_limits<opus_int32>::max())) {
+            throw_value_error("Input is too large to decode.");
+        }
+
+        int error = 0;
+        OggOpusFile *opus_file = op_open_memory(
+            reinterpret_cast<const unsigned char *>(encoded.data()), static_cast<opus_int32>(encoded.size()), &error);
+        if (opus_file == nullptr) {
+            throw py::value_error(("Failed to parse opus stream, op_open_memory error=" + std::to_string(error)).c_str());
+        }
+
+        const int channels = op_channel_count(opus_file, -1);
+        if (channels <= 0 || channels > 8) {
+            op_free(opus_file);
+            throw_value_error("Invalid channel count from opus stream.");
+        }
+
+        std::vector<int16_t> pcm;
+        std::vector<int16_t> frame(static_cast<size_t>(kMaxSamplesPerChannel * channels));
+
+        while (true) {
+            const int samples = op_read(opus_file, frame.data(), static_cast<int>(frame.size()), nullptr);
+            if (samples == 0) {
+                break;
+            }
+            if (samples < 0) {
+                op_free(opus_file);
+                throw py::value_error(("Decode failed, op_read error=" + std::to_string(samples)).c_str());
+            }
+            pcm.insert(pcm.end(), frame.begin(), frame.begin() + static_cast<size_t>(samples * channels));
+        }
+
+        op_free(opus_file);
+
+        const auto sample_count = static_cast<ssize_t>(pcm.size() / static_cast<size_t>(channels));
+        py::array_t<int16_t> output({sample_count, static_cast<ssize_t>(channels)});
+        if (!pcm.empty()) {
+            std::memcpy(output.mutable_data(), pcm.data(), pcm.size() * sizeof(int16_t));
+        }
+        return output;
+    }
+};
+
+PYBIND11_MODULE(opuscodec, m) {
+    m.doc() = "Python bindings for opusenc/opusdec with vendored libopus builds";
+
+    py::class_<OpusBufferedEncoder>(m, "OpusBufferedEncoder")
+        .def(py::init<int, int, int, int, int, int, bool>(),
+             py::arg("sample_rate"),
+             py::arg("channels"),
+             py::arg("bitrate") = OPUS_AUTO,
+             py::arg("signal_type") = 0,
+             py::arg("encoder_complexity") = 10,
+             py::arg("decision_delay") = 0,
+             py::arg("qext") = kQextDefaultEnabled)
+        .def("write", &OpusBufferedEncoder::write, py::arg("buffer"))
+        .def("flush", &OpusBufferedEncoder::flush)
+        .def("close", &OpusBufferedEncoder::close)
+        .def("qext_enabled", &OpusBufferedEncoder::qext_enabled);
+
+    py::class_<OpusBufferedDecoder>(m, "OpusBufferedDecoder")
+        .def(py::init<>())
+        .def("decode", &OpusBufferedDecoder::decode, py::arg("opus_data"));
+
+    m.def("opus_version", []() { return std::string(opus_get_version_string()); });
+#if defined(OPUSCODEC_QEXT_ENABLED)
+    m.def("qext_enabled", []() { return true; });
+#else
+    m.def("qext_enabled", []() { return false; });
+#endif
+}

opuscodec-0.1.2/tests/test_bindings.py

@@ -0,0 +1,83 @@
+import os
+
+import numpy as np
+import pytest
+
+import opuscodec
+
+
+def _make_pcm(sample_rate: int = 48_000, seconds: float = 1.0, channels: int = 1) -> np.ndarray:
+    t = np.arange(int(sample_rate * seconds), dtype=np.float64) / sample_rate
+    mono = 0.2 * np.sin(2 * np.pi * 440 * t)
+    pcm = (mono * 32767).astype(np.int16)
+    if channels == 1:
+        return pcm.reshape(-1, 1)
+    return np.repeat(pcm.reshape(-1, 1), channels, axis=1)
+
+
+def _best_aligned_corr(x: np.ndarray, y: np.ndarray) -> float:
+    x = x.astype(np.float64)
+    y = y.astype(np.float64)
+    corr = np.correlate(y, x, mode="full")
+    lag = int(np.argmax(np.abs(corr)) - (len(x) - 1))
+    if lag >= 0:
+        x_aligned = x[: len(y) - lag]
+        y_aligned = y[lag : lag + len(x_aligned)]
+    else:
+        y_aligned = y[: len(x) + lag]
+        x_aligned = x[-lag : -lag + len(y_aligned)]
+
+    n = min(len(x_aligned), len(y_aligned))
+    if n < 1000:
+        return 0.0
+    x_aligned = x_aligned[:n]
+    y_aligned = y_aligned[:n]
+    return float(np.corrcoef(x_aligned, y_aligned)[0, 1])
+
+
+def test_encode_decode_roundtrip() -> None:
+    pcm = _make_pcm(channels=1)
+
+    encoder = opuscodec.OpusBufferedEncoder(sample_rate=48_000, channels=1, bitrate=64_000)
+    encoded = b""
+    for i in range(0, len(pcm), 960):
+        encoded += encoder.write(pcm[i : i + 960])
+    encoded += encoder.flush()
+
+    decoder = opuscodec.OpusBufferedDecoder()
+    decoded = decoder.decode(encoded)
+
+    assert decoded.dtype == np.int16
+    assert decoded.ndim == 2
+    assert decoded.shape[1] == 1
+    assert decoded.shape[0] > 10_000
+
+    corr = _best_aligned_corr(pcm[:, 0], decoded[:, 0])
+    assert corr > 0.70
+
+
+def test_encoder_rejects_invalid_channels() -> None:
+    with pytest.raises(ValueError):
+        opuscodec.OpusBufferedEncoder(sample_rate=48_000, channels=0)
+
+
+def test_flush_requires_write() -> None:
+    encoder = opuscodec.OpusBufferedEncoder(sample_rate=48_000, channels=1)
+    with pytest.raises(ValueError):
+        encoder.flush()
+
+
+def test_qext_default_enabled() -> None:
+    expected = os.environ.get("OPUSCODEC_ENABLE_QEXT", "1") != "0"
+    assert opuscodec.qext_enabled() is expected
+
+
+def test_encoder_qext_runtime_default_enabled() -> None:
+    encoder = opuscodec.OpusBufferedEncoder(sample_rate=48_000, channels=1)
+    expected = os.environ.get("OPUSCODEC_ENABLE_QEXT", "1") != "0"
+    assert encoder.qext_enabled() is expected
+
+
+def test_encoder_qext_runtime_can_disable() -> None:
+    encoder = opuscodec.OpusBufferedEncoder(sample_rate=48_000, channels=1, qext=False)
+    assert encoder.qext_enabled() is False