{"id":17039007,"url":"https://github.com/dcnick3/unsafe-libopus","last_synced_at":"2025-04-12T14:02:19.764Z","repository":{"id":65842311,"uuid":"601170101","full_name":"DCNick3/unsafe-libopus","owner":"DCNick3","description":"libopus transpiled to rust by c2rust","archived":false,"fork":false,"pushed_at":"2024-11-21T20:20:50.000Z","size":3458,"stargazers_count":10,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-06T04:30:57.960Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DCNick3.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-13T14:12:35.000Z","updated_at":"2024-10-02T01:45:18.000Z","dependencies_parsed_at":"2024-06-28T19:47:06.561Z","dependency_job_id":"aa25a755-6ce9-4bf8-810f-aa1094924aed","html_url":"https://github.com/DCNick3/unsafe-libopus","commit_stats":{"total_commits":99,"total_committers":1,"mean_commits":99.0,"dds":0.0,"last_synced_commit":"501cf67dbb5ba0e854855a42841246751406ee50"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DCNick3%2Funsafe-libopus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DCNick3%2Funsafe-libopus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DCNick3%2Funsafe-libopus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DCNick3%2Funsafe-libopus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DCNick3","download_url":"https://codeload.github.com/DCNick3/unsafe-libopus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233794920,"owners_count":18731360,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-14T08:58:25.622Z","updated_at":"2025-01-13T18:59:08.709Z","avatar_url":"https://github.com/DCNick3.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# unsafe-libopus\n\nThis library is [libopus](https://github.com/xiph/opus) 1.3.1 translated from C to unsafe Rust with the assistance\nof [c2rust](https://github.com/immunant/c2rust).\n\nIt is called \"unsafe\" libopus, because it still pretty much has the same shape as the C code and is full of \"unsafe\".\n\nThis translation still allows you to get rid of C compiler toolchain and use the library in a pure rust environment,\nwithout linker hackery \u0026 dynamic linking issues.\n\nIt also may potentially be a starting point for a more idiomatic rust implementation of libopus, though I am not sure if\nit is worth the effort.\n\n## Usage\n\nYou can leverate this library by using a fork of `opus` crate\nfrom [this PR](https://github.com/SpaceManiac/opus-rs/pull/20):\n\n```toml\n[dependencies]\nopus = { git = \"https://github.com/DCNick3/opus-rs.git\", branch = \"unsafe-libopus\", default-features = false, features = [\"unsafe-libopus-backend\"] }\n```\n\nMaybe, this library will have the safe APIs in the future, but for now, it is a (mostly) drop-in replacement for\nthe `audiopus_sys` crate.\n\n## Translation technique\n\nFirstly, the [libopus 1.3.1](https://archive.mozilla.org/pub/opus/opus-1.3.1.tar.gz) was compiled with the following\ncommands:\n\n```bash\nCC=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\nCC=clang compiledb make -j\n```\n\nThen, using the resulting `compile_commands.json` file, the C code was transpiled to rust with:\n\n```bash\nc2rust transpile compile_commands.json -o . --overwrite-existing --reorganize-definitions --emit-modules --translate-const-macros --emit-build-files\n```\n\nThe resulting code was then manually reorganized, to remove all duplication of structures \u0026 eradicate the use\nof `#[no_mangle] extern \"C\"` functions: they are all linked with rust now and do not have to exported.\n\nSome other refactorings include:\n\n- separation of the test binaries from the library as \"examples\"\n- removal of dependencies of libc functions in the library by defining their variants in the library (idea\n  from [unsafe-libyaml](https://github.com/dtolnay/unsafe-libyaml))\n- removal of dependency on the libc crate by replacing the libc types with concrete rust types (`libc::c_int` -\u003e `i32`,\n  etc)\n- removal of C varargs by replacing them with a custom VarArgs struct, as C variadics are not yet stable in rust. This\n  turns the `opus_*_ctl` family of functions into macros\n\n## Performance\n\nThe library was translated without the use of inline assembly, processor intrinsics and runtime CPU detection, so it is\nnot as fast as the original code right now. The C version with those features is about 20% faster than the rust version\non my machine.\n\n## Correctness\n\nThis library is tested using (most of) the original tests from the C codebase. They are present in form of rust\nintegration tests in the `tests` directory. Still not translated are a bunch of unit tests from the C codebase.\n\nThe crux of the testing happens in the `unsafe-libopus-tools/src/bin/run_vectors2.rs` though.\nIt tests both the decoder and encoder using IETF-published test vectors,\ncomparing the results with the C implementation of opus 1.3.1 located in `upstream-libopus`.\nIt does have a small number of patches to make the results more portable.\n\nThe decoder is tested by decoding the test vectors and comparing the results with the C implementation at a\nnumber of output sample rates.\nThey are checked to match exactly.\n\nThe same is done to the encoder,\nrunning at a number of different bitrates and comparing the encoded results with the C implementation.\nAside from bitrate, no other parameters are changed, which currently is a weak point of the testing.\n\nStrictly speaking, same encoded results are not required for this to be a valid implementation: the encoder is free to\ndo a lot of choices, leaving to different quality results.\nHowever, making a codec that is _better_ than the original opus is a non-goal. Therefore, by requiring the exact same\nresults, we prevent any divergence in the behavior of the encoder.\n\n## Safety\n\nCurrently, most of the code is unsafe, as it is a direct transpilation of the C code.\n\nI am currently in the process of slowly refactoring the code to make certain parts of it safe. Previously maintaining\nvalidity was a challenge, but now that there are tests checking the implementation against the C code, it should become\neasier.\n\n![](https://unsafe-track.dcnick3.me/github/DCNick3/unsafe-libopus?x_coord=Index\u0026y_coord=Functions\u0026path_filter=^/src/(celt/([^/]*\\.rs|modes/[^/]*\\.rs)|silk/([^/]*\\.rs|float/[^/]*\\.rs|resampler/[^/]*\\.rs)|src/.*\\.rs)$)\n\n## License\n\nSame as the original libopus, `unsafe-libopus` is licensed under the BSD 3-clause license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdcnick3%2Funsafe-libopus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdcnick3%2Funsafe-libopus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdcnick3%2Funsafe-libopus/lists"}