Where it already goes beyond JUCE

Check it

automation_lands_on_its_exact_frame_and_updates_the_parameter schedules changes on frames 100, 101 and 250 and asserts the output sample by sample. automation_lands_on_its_frame_when_processing_in_place does the same through the CLAP C interface, and a test of the same name does it through VST 3, where a host sends a queue of points per parameter and every point is delivered. (JUCE’s VST3 wrapper applies the last point of each queue: processParameterChanges in juce_audio_plugin_client_VST3.cpp.)

VST 3 adds a trap of its own. A host reports each change twice: to the processor with a frame number, and to the controller on the main thread so that an editor can follow. If the controller’s copy is stored into the parameter, the plugin jumps to a value that is slightly early or late until the next point corrects it. While blocks are running, Manguebyte’s wrapper keeps the controller’s copy for display only; what_the_controller_is_told_does_not_disturb_running_automation checks it.

• pluginautomation_lands_on_its_exact_frame_and_updates_the_parameterok
• clapautomation_lands_on_its_frame_when_processing_in_placeok
• vst3automation_lands_on_its_frame_when_processing_in_placeok
• vst3what_the_controller_is_told_does_not_disturb_running_automationok

#[test]
fn automation_lands_on_its_exact_frame_and_updates_the_parameter() {
    let mut harness = Harness::<Level>::new(48_000.0, 64);
    harness.automate(100, "level", 2.0);
    harness.automate(101, "level", 3.0);
    harness.automate(250, "level", 0.5);

    let output = harness.process(&ones(2, 300));
    let left = output.channel(0);
    assert_eq!(&left[..100], &[1.0; 100]);
    assert_eq!(left[100], 2.0);
    assert_eq!(&left[101..250], &[3.0; 149]);
    assert_eq!(&left[250..], &[0.5; 50]);
    assert_eq!(output.channel(1), left);

    // Anything polling the parameter sees where automation left it.
    assert_eq!(harness.params().level.value(), 0.5);
    assert_eq!(harness.position(), 300);
}

Check it

the_song_is_the_same_whatever_the_block_size renders a polyphonic song with effects and automation six ways: 64, 256, 997 and 1024 frames, an irregular pattern of 1, 511, 7, 300, 64, 2, 129, and blocks larger than the instrument’s own maximum. The results must be equal bit for bit. Both example plugins have the same test: the instrument and the effect.

The first time this test ran, it failed. A voice that had finished in the middle of a block kept advancing until the end of it, so the next note started from a state that depended on the block length. The test exists to find exactly that, and the fix is part of the Voice contract.

• manguebytethe_song_is_the_same_whatever_the_block_sizeok
• plucksounds_the_same_whatever_the_block_sizeok
• ducksounds_the_same_whatever_the_block_sizeok

#[test]
fn the_song_is_the_same_whatever_the_block_size() {
    let reference = render(256, &[256]);
    assert!(reference.peak() > 0.1, "the reference render is silent");

    for (max_block_size, pattern) in [
        (64, &[64][..]),
        (1024, &[1024]),
        // Odd lengths that never line up with a note boundary.
        (997, &[997]),
        // A host that changes its mind on every call.
        (512, &[1, 511, 7, 300, 64, 2, 129]),
        // Blocks larger than the player's own, which it must split itself.
        (48, &[5_000]),
    ] {
        let other = render(max_block_size, pattern);
        assert!(
            other == reference,
            "blocks of {pattern:?} (max {max_block_size}) changed the output"
        );
    }
}

Check it

changes_made_outside_the_host_reach_the_plugin_as_events uses a test plugin that never reads its parameter, only events. It passes for a direct write, for a restored state, and for host automation on the same frame, which takes precedence.

• pluginchanges_made_outside_the_host_reach_the_plugin_as_eventsok

Check it

processors_do_not_use_the_heap and its neighbours cover every processor, the FFT, a synth handling more notes than it has voices, and parameter changes made while running. A test of the guard itself makes sure it would notice. Through the CLAP interface, heap_calls must be zero for automation, notes, changes reported to the host and the block after a state restore.

The guard has already earned its place. On macOS it reported one heap call inside process: a test plugin was recording a value through a standard mutex, which on that platform allocates the first time it is locked.

• dspprocessors_do_not_use_the_heapok
• dspa_synth_handles_a_flood_of_events_without_using_the_heapok
• dspthe_guard_itself_catches_an_allocationok
• clapheap_calls == 0 through the CLAP interfaceok
• ciCI job: Miriok

/// Runs `work` and panics if it used the heap in any way.
fn assert_no_heap_use(what: &str, work: impl FnOnce()) {
    HEAP_CALLS.with(|calls| calls.set(0));
    WATCHING.with(|watching| watching.set(true));
    work();
    WATCHING.with(|watching| watching.set(false));
    let calls = HEAP_CALLS.with(Cell::get);
    assert_eq!(
        calls, 0,
        "{what} used the heap {calls} time(s) while processing"
    );
}

/// Prepares a processor, then runs it over blocks of several sizes with the
/// allocator watched.
fn check<P: Processor<f32>>(what: &str, mut processor: P) {
    processor.prepare(&SPEC);
    let mut buffer = AudioBuffer::<f32>::new(SPEC.num_channels, SPEC.max_block_size);
    assert_no_heap_use(what, || {
        for frames in [256, 1, 64, 255, 256] {
            buffer.set_num_frames(frames);
            for channel in buffer.iter_channels_mut() {
                channel.fill(0.25);
            }
            processor.process(&mut buffer);
        }
        processor.reset();
        buffer.set_num_frames(256);
        processor.process(&mut buffer);
    });
}

Check it

expression_and_modulation_reach_one_note_and_parameters_reach_all and notes_with_identifiers_overlap_on_one_key_and_end_separately in the synth; an_instrument_takes_notes_expression_modulation_and_a_sidechain does it through CLAP.

• dspexpression_and_modulation_reach_one_note_and_parameters_reach_allok
• dspnotes_with_identifiers_overlap_on_one_key_and_end_separatelyok
• clapan_instrument_takes_notes_expression_modulation_and_a_sidechainok

Check it

The CI job builds both example plugins and runs the CLAP project’s own clap-validator on them, failing on any failed test. At the commit this site was written against, the validator ran 44 tests on each: the instrument passed 35 and skipped 9, the effect passed 33 and skipped 11, and neither failed any. The skipped tests are for things the plugins do not have yet: preset discovery (3 tests), 64-bit audio (2) and the extensions that let a host reconfigure the audio ports (3). The instrument also skips a test that feeds it audio, because it has no audio input, and the effect skips the three note tests, because it takes no notes.

cargo mangue bundle writes the .clap beside the .vst3 in each system’s layout, and cargo mangue validate runs the CLAP project’s validator on it as well as Steinberg’s on the .vst3; a CI job runs the tool end to end on Windows, Linux and macOS. JUCE’s juce_add_plugin accepts no CLAP format.

• ciCI job: CLAP validationok
• duckplugins/duck/src/lib.rsok
• ciCI job: command-line tool end to endok

Check it

The example instrument’s tests check that it is silent until played, that it plays the pitch it is asked for (by FFT), that automation and per-note modulation change the sound, that state round-trips, and that the output is independent of block size. The example effect’s tests feed its sidechain the same way.

• pluckplays_the_pitch_it_is_asked_forok
• duckautomation_lands_on_its_frame_with_audio_running_throughok
• plucksounds_the_same_whatever_the_block_sizeok

#[test]
fn plays_the_pitch_it_is_asked_for() {
    use manguebyte::dsp::fft::{Complex, RealFft};

    let mut harness = Harness::<Pluck>::new(RATE, 512);
    harness.params().reverb.set(0.0);
    // No resonant peak, so the fundamental is the loudest partial.
    harness.params().resonance.set(0.7);
    harness.note(0, 40_000, 69, 1.0); // A4, 440 Hz
    let sound = harness.render(32_768);

    let mut fft = RealFft::<f32>::new(32_768);
    let mut spectrum = vec![Complex::ZERO; fft.spectrum_len()];
    fft.forward(sound.channel(0), &mut spectrum);
    let loudest = (1..spectrum.len())
        .max_by(|&a, &b| spectrum[a].norm_sqr().total_cmp(&spectrum[b].norm_sqr()))
        .unwrap();
    let hertz = loudest as f64 * RATE / 32_768.0;
    assert!((hertz - 440.0).abs() < 2.0, "loudest partial at {hertz} Hz");
}

Check it

state_from_another_version_loads_as_far_as_it_can and params_are_shareable_across_threads in the parameters crate.

• paramsstate_from_another_version_loads_as_far_as_it_canok
• paramsparams_are_shareable_across_threadsok

Check it

The two licence texts in the repository: MIT and Apache-2.0.

• fileLICENSE-MITok
• fileLICENSE-APACHEok

Check it

A test in both wrappers (CLAP, VST 3) has a plugin report what the processor does with a subnormal number from inside process, then checks that the host’s thread is back to its own setting afterwards, including after the plugin panics. Measured on the example effect, 4,000 blocks of subnormal input took 442 ms without the guard and 31 ms with it.

• clapnumbers_too_small_to_hear_are_zero_while_the_plugin_runs_and_only_thenok
• vst3numbers_too_small_to_hear_are_zero_while_the_plugin_runs_and_only_thenok
• corecrates/manguebyte-core/src/denormal.rsok

Check it

Compile-fail doc-tests on ClapPlugin and Vst3Plugin show that the main-thread half cannot be sent to another thread. the_hosted_plugin_sounds_exactly_as_the_plugin_does_alone, for CLAP and for VST 3, loads the example instrument through its real entry point and requires its output to be identical bit for bit to the same plugin run in process by Harness, for four block layouts, with automation of five parameters, notes with ids, expression and pitch bend; removing any one kind of event changes the output, so the identity is not two deaf paths agreeing. automation_lands_on_its_frame_through_the_host sends 59 VST 3 points 61 frames apart.

• hostthe_hosted_plugin_sounds_exactly_as_the_plugin_does_aloneok
• hostthe_hosted_plugin_sounds_exactly_as_the_plugin_does_aloneok
• hostautomation_lands_on_its_frame_through_the_hostok
• hostprocessing_never_uses_the_heapok
• ciCI job: Miri (plugin host)ok

Check it

ebu_tech_3341.rs synthesises the EBU Tech 3341 test signals and requires cases 1 to 6 and 9 to 14 within 0.1 LU, and the true-peak cases 15 to 23 within +0.2/−0.4 dB; ebu_tech_3342.rs does the same for loudness range, cases 1 to 4. The VU needle reaches 99% in 300 ms ±3 ms with 1.0 to 1.5% overshoot at 44.1 to 192 kHz. Readings are identical to the bit whatever the block size, and measuring makes no heap call.

• analysiscases_1_and_2_a_steady_tone_reads_its_level_on_all_three_scalesok
• analysiscases_15_to_19_a_sine_is_read_at_its_crest_wherever_the_samples_fallok
• analysiscase_1_two_tones_ten_decibels_apartok

Check it

a_time_tag_lands_on_its_exact_frame, every_frame_of_a_block_can_be_hit and where_an_event_lands_does_not_depend_on_the_block_size (400 events, seven block patterns, identical frames); reading on the audio thread makes no heap call. codec.rs encodes the specification’s examples byte for byte and round-trips every type.

• osca_time_tag_lands_on_its_exact_frameok
• oscevery_frame_of_a_block_can_be_hitok
• oscwhere_an_event_lands_does_not_depend_on_the_block_sizeok
• oscthe_examples_in_the_specification_encode_byte_for_byteok

Check it

pitch.rs: sines, sawtooths, square waves, tones without their fundamental and tones with a strong second harmonic from 55 Hz to 2 kHz read within 2 cents at 44.1 and 48 kHz, with no octave errors. spectrum.rs: a full-scale sine reads 0 dB in its band within 0.01 dB, and the third-octave bands of white and pink noise add up within 0.05 dB.

• analysisevery_test_tone_is_found_within_a_centok
• analysisa_full_scale_sine_reads_0_db_in_its_bandok
• analysisbands_of_white_and_pink_noise_read_the_power_that_lies_in_themok

Check it

the_keyboard_state_does_not_use_the_heap (20,000 random messages, reads interleaved), and a_key_that_goes_on_sounding_is_never_read_as_silent and an_interface_can_read_while_another_thread_writes.

• midithe_keyboard_state_does_not_use_the_heapok
• midia_key_that_goes_on_sounding_is_never_read_as_silentok
• midian_interface_can_read_while_another_thread_writesok