Skip to content

README.md

Latest commit

 

History

History
77 lines (55 loc) · 5.18 KB

README.md

File metadata and controls

77 lines (55 loc) · 5.18 KB
Raw

Rustacity

Rustacity

An Audacity v2.4.1 fork created for the Rustaceans.

Rustacity is an easy-to-use, multi-track audio editor and recorder for Windows, Mac OS X, GNU/Linux and other operating systems. It keeps everything you know about Audacity, and grows a Rust core under it: parts of the audio processing, and a sandboxed WebAssembly engine for extensions.

  • Recording from any real, or virtual audio device that is available to the host system.
  • Export / Import a wide range of audio formats, extendible with FFmpeg.
  • High quality using 32-bit float audio processing.
  • Plug-ins Support for multiple audio plug-in formats, including VST, LV2, AU.
  • Macros for chaining commands and batch processing.
  • Scripting in Python, Perl, or any language that supports named pipes.
  • Nyquist Very powerful built-in scripting language that may also be used to create plug-ins.
  • Editing multi-track editing with sample accuracy and arbitrary sample rates.
  • Accessibility for VI users.
  • Analysis and visualization tools to analyze audio, or other signal data.

Documentation
Repository layout what each top-level directory is, what is ours, what is vendored, and what has been removed
Architecture the C++ shell and the Rust core, the C ABI, the panic policy, what CI proves, and how a unit is ported
Port status which DSP units are Rust, which are not yet, and why
Golden values how each port is checked against the implementation it replaced
Extensions the sandboxed WebAssembly extension engine: the API contract, the sandbox, how to write an extension, and what is not built yet
Roadmap what has moved to Rust, that the extension API has landed, and what the editor side still needs

Getting Started

Rustacity is built from source with CMake. The build compiles the Rust cores and links them, so a Rust toolchain is required in addition to a C++ one, and wxWidgets is not optional: the build wants the pinned fork (audacity/wxWidgets, branch audacity-fixes-3.1.3).

The canonical recipe per platform is the CI workflow, .github/workflows/cmake_build.yml - what it runs is what produces the releases.

Because Rustacity is a fork of Audacity 2.4.1, end-user documentation, forums, and developer references are still available from the upstream Audacity website, Audacity Forum, and Audacity Wiki.

The Rust DSP core

Parts of the audio processing are implemented in Rust, in the rustacity-dsp crate under rust/dsp/. The build invokes cargo and links the crate as a static library; the C interface between the two halves is rust/dsp/include/rustacity_dsp.h.

The ported code is checked against reference values captured from the original C++ implementation (rust/dsp/goldens/reference.txt):

cd rust
cargo test --workspace

The ABI conventions, the panic policy and the rules for porting more of the audio engine to Rust are in docs/architecture.md, with the crate-level detail in rust/README.md.

The extension engine

Beside the DSP core, rust/ext-host/ runs sandboxed WebAssembly extensions: a directory with a manifest (extension.toml) and a module (extension.wasm) exporting eight functions. An extension gets the audio in blocks, one import for logging, and nothing else - no filesystem, no network, no environment - and a call that runs past its deadline, traps or runs out of memory takes that invocation down rather than the editor.

The contract is docs/extensions/API.md, what the sandbox does and does not promise is docs/extensions/SANDBOX.md, and docs/extensions/WRITING_AN_EXTENSION.md is the practical guide. The editor-side plumbing - where extensions are installed, the menu entry per extension and the parameter dialog - is not in place yet; docs/extensions/INTEGRATION_NOTES.md is precise about what is and is not built.

Releasing

Releases are cut from main with an annotated tag, whose name is the release number; the version the application itself reports stays the upstream 2.4.x string it has always been:

git tag -a rustacity-0.4.0 -F notes.md   # the tag message is the release prose
git push origin rustacity-0.4.0

The tag push runs the Publish Release job. It waits for the build matrix and the Rust tests, takes the packages from the run and names each one after the platform it holds (rustacity-<platform>-<version>-<arch>.<extension>): Windows ships the archive and both installers, macOS a disk image, Linux an AppImage. It attaches the tree the tag names (rustacity-sources-<version>.tar.xz) and publishes the GitHub release with notes generated from the commits since the previous tag.