![vorbis-rs logo](https://private-user-images.githubusercontent.com/7822554/289361381-c12d850c-8924-41fa-b2f3-9d00e18bd7bc.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjM4OTIyMzAsIm5iZiI6MTcyMzg5MTkzMCwicGF0aCI6Ii83ODIyNTU0LzI4OTM2MTM4MS1jMTJkODUwYy04OTI0LTQxZmEtYjJmMy05ZDAwZTE4YmQ3YmMucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI0MDgxNyUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNDA4MTdUMTA1MjEwWiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9MTIzZTIxNjRjYTRkMDdlZmQyYmY4OTNjNDg5NmQ5YjRiZGY4MmIxMDk5NjEzNjQxNjUwMGE3N2VkMmU4NjlkMSZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmYWN0b3JfaWQ9MCZrZXlfaWQ9MCZyZXBvX2lkPTAifQ.ltZ6dcXPgyZjVHOVdiI7eKz83E6iOA202uW55qd2LU0)
Rust bindings for the best-in-breed C libraries of the Vorbis audio codec and Ogg container encapsulation.
The vorbis_rs
package in this repository provides updated, well-documented and
ergonomic bindings for a modified version of the latest reference Vorbis
encoder, available here, with
the aoTuV and
Lancer
patchsets applied to it. These patches are considered to implement significant
encoding quality and performance improvements by the community.
The supporting aotuv_lancer_vorbis_sys
and ogg_next_sys
packages provide
automatically-generated low-level bindings used by vorbis_rs
.
The minimum supported Rust version (MSRV) for every package in this repository is 1.64. Bumping this version is not considered a breaking change for semantic versioning purposes. We will try to do it only when we estimate that such a bump would not cause widespread inconvenience or breakage.
The Rust ecosystem already has bindings for these libraries (see
vorbis-sys
and
vorbis
), but the quality and maintenance
status of the available crates is problematic in an entangled way that does not
seem reasonable to fix via PRs or patching:
- The high-level
vorbis
crate was not updated in 6 years, has arguably low code quality (lots ofpanic!
with messages containing e-mail addresses, etc.), and depends on an old version ofvorbis-sys
. In turnvorbis-sys
depends on an old version of thelibvorbis
C library with known security vulnerabilities. It also lacks APIs to do some operations needed by sensible audio processing applications that are offered by the C libraries. vorbis-sys
only contains bindings forlibvorbis
, but updated bindings forlibvorbisenc
andvorbisfile
are necessary to do meaningful Vorbis stream operations in a sane way. These are not available either.- There are several random crates in crates.io depending on several of these unsatisfactory binding projects, and it seems unlikely that their maintainers will promptly accept breaking changes on them, generating ecosystem fragmentation.
- Like most software libraries, frameworks and even Linux distributions, the existing crates seem to be oblivious to the existence of the aoTuV and Lancer patchsets, even though they are meant to be drop-in replacements. Thus, users may reasonably expect any patches to be mentioned, which is a good reason to do a different set of binding crates anyway.
Given these issues and the need for a better solution for Ogg Vorbis audio processing applications in Rust, it was decided to spend development effort on making new bindings: it was estimated that the upfront cost of fixing the technical debt of the ecosystem was higher than starting bindings from scratch and periodically updating the library bindings from upstream. Rewriting the patched Vorbis encoder in Rust was deemed unfeasible.
The bindings in this repository are licensed under the BSD 3-Clause "New" or
"Revised" License (LICENSE
or https://opensource.org/licenses/BSD-3-Clause),
which is the same permissive license used by the upstream projects.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in vorbis_rs by you shall be licensed as above, without any additional terms or conditions.
This repository started as an ad-hoc solution to address the needs of a Rust application, but it has grown into a project of its own - PRs are welcome!
The C libraries sources are managed with submodules, so updating the binding crates with the latest upstream changes should be easy:
- Update the submodules.
- Run the
generate-bindings.sh
script on a Unix-like system (Linux, macOS, BSD) withrust-bindgen
, or build the project withcargo build --features build-time-bindgen
. This will regenerate the low-level FFI bindings according to the latest source code. - Run
cargo test
. This will execute some basic sanity checks, including encoding and decoding example files, to check that the bindings still work. - Review the changes and/or fix failing tests until there is reasonable confidence that the upgrade was completed successfully.
- Commit the changes.
When cloning the repository, remember to also check out the submodules with the
vendor code. You can do this by running git submodule update --init --recursive
.
Each time vendor code is updated, it will be necessary to release a new version
of aotuv_lancer_vorbis_sys
and/or ogg_next_sys
, so that users of vorbis_rs
can download binding crates with the updated vendor code.
We welcome friendly talk about the project, including questions, congratulations, and suggestions. Head to the GitHub Discussions page to interact with fellow users, contributors and developers.
Thanks goes to these wonderful people (emoji key):
Alejandro GonzΓ‘lez π» π π‘ π§ π |
Vivian π» π€ |
Martin Algesten π» |
Kyle Chen π€ |
Daniel Collin π |
This project follows the all-contributors specification. Contributions of any kind welcome!