unsafe-libopus

This library is libopus 1.3.1 translated from C to unsafe Rust with the assistance of c2rust.

It is called "unsafe" libopus, because it still pretty much has the same shape as the C code and is full of "unsafe".

This translation still allows you to get rid of C compiler toolchain and use the library in a pure rust environment, without linker hackery & dynamic linking issues.

It also may potentially be a starting point for a more idiomatic rust implementation of libopus, though I am not sure if it is worth the effort.

Usage

You can leverate this library by using a fork of opus crate from this PR:

[dependencies]
opus = { git = "https://github.com/DCNick3/opus-rs.git", branch = "unsafe-libopus", default-features = false, features = ["unsafe-libopus-backend"] }

Maybe, this library will have the safe APIs in the future, but for now, it is a (mostly) drop-in replacement for the audiopus_sys crate.

Translation technique

Firstly, the libopus 1.3.1 was compiled with the following commands:

CC=clang ./configure --disable-shared --disable-stack-protector --enable-extra-programs --disable-doc --disable-asm --disable-rtcd --disable-intrinsics --disable-dependency-tracking--disable-maintainer-mode --enable-hardening
CC=clang compiledb make -j

Then, using the resulting compile_commands.json file, the C code was transpiled to rust with:

c2rust transpile compile_commands.json -o . --overwrite-existing --reorganize-definitions --emit-modules --translate-const-macros --emit-build-files

The resulting code was then manually reorganized, to remove all duplication of structures & eradicate the use of #[no_mangle] extern "C" functions: they are all linked with rust now and do not have to exported.

Some other refactorings include:

• separation of the test binaries from the library as "examples"
• removal of dependencies of libc functions in the library by defining their variants in the library (idea from unsafe-libyaml)
• removal of dependency on the libc crate by replacing the libc types with concrete rust types (libc::c_int -> i32, etc)
• removal of C varargs by replacing them with a custom VarArgs struct, as C variadics are not yet stable in rust. This turns the opus_*_ctl family of functions into macros

Performance

The library was translated without the use of inline assembly, processor intrinsics and runtime CPU detection, so it is not as fast as the original code right now. The C version with those features is about 20% faster than the rust version on my machine.

Correctness & Safety

This library is tested using (most of) the original tests from the C codebase. They are present in form of rust integration tests in the tests directory.

The opus test vectors are also used to test the library decoder in CI (see the src/bin/run_vectors.rs). This pretty much ensures that the decoder is correct. This actually helped uncover a subtle bug in c2rust.

The correctness of the encoder is a bit more of an open question, as there are no test vectors for it, AFAIK. There is some testing going on in tests/opus_encode, but it's quite limited.

As for the safety, no guarantees are made. The code is a result of a pretty direct transpilation of the C code, so it is almost entirely consists of unsafe code (in rust terms).

It also seems to have UB according to miri, but those are probably false positives. A good refactoring goal might be to make the library pass miri checks.