1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143
// Augmented Audio: Audio libraries and applications
// Copyright (c) 2022 Pedro Tacla Yamada
//
// The MIT License (MIT)
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.
//! [![crates.io](https://img.shields.io/crates/v/audio-processor-standalone-midi.svg)](https://crates.io/crates/audio-processor-standalone-midi)
//! [![docs.rs](https://docs.rs/audio-processor-standalone-midi/badge.svg)](https://docs.rs/audio-processor-standalone-midi/)
//! - - -
//!
//! This crate provides conversion into the VST types, which is to allow a VST host to use it. This is provided by the
//! `MidiVSTConverter`.
//!
//! Wraps `midir` to provide MIDI input handling. The host may be started with `MidiHost`.
//!
//! When MIDI messages are received, they're pushed onto a lock-free `atomic_queue::Queue`. The messages are picked-up in
//! the audio-thread by `MidiAudioThreadHandler`.
//!
//! It provides easy stand-alone MIDI integration with:
//!
//! * `audio-processor-traits` - `MidiEventHandler` trait
//! * `rust-vst` - `PluginInstance`
//!
//! Currently, MIDI messages over 3 bytes are dropped by this host. In addition, the queue is bounded & a size must be
//! provided. `Default` implementations will use a MIDI queue capacity of 100.
//! This is a stand-alone MIDI host with helpers for doing real-time handling of MIDI messages in
//! the audio-thread and to integrate with VST plugins.
//!
//! This is part of https://github.com/yamadapc/augmented-audio.
//!
//! # Memory Safety
//! In order to integrate with the VST C API, this crate does manual memory allocation and handling. This is due to VST
//! event types being unrepresentable as safe Rust constructs (and due to real-time safety being required as well).
//!
//! # Real-time Safety
//! This crate provides the `host` side, which is the MIDI host. This host allocates when it receives messages from `midir`.
//!
//! The events are forwarded onto a lock-free queue (`atomic_queue`).
//!
//! On the `audio_thread` and `vst` modules, past construction methods that should be called on the audio-thread will not
//! (de)-allocate. This is tested using the `assert_no_alloc` crate.
//!
//! In addition, `basedrop` / `audio_garbage_collector` are used to prevent de-allocation from happening on the
//! audio-thread.
//!
//! # Test coverage
//! The crate has unit-tests (though it should be considered experimental as all of this repository).
//!
//! Test coverage is at 80%.
//!
//! # Actix & Actors
//! The `MidiHost` exposes an actix API, to be used with the actix actor system. This is to ease communicating with the midi
//! handler from multiple threads.
//!
//! # Usage
//! To use this crate:
//!
//! * [`basedrop::Collector`] You'll need to set-up `basedrop` or `audio-garbage-collector`
//! * [`host::MidiHost`] should be created
//! - This will connect to inputs & push messages to a queue
//! * [`audio_thread::MidiAudioThreadHandler`] On your audio thread you should pop from the queue
//! - This is enough to add MIDI to a standalone [`audio_processor_traits::MidiEventHandler`]
//! * [`vst::MidiVSTConverter`] If you're implementing a host, you'll have to convert messages onto
//! the VST API
//!
//! ```
//! fn example() {
//! use audio_processor_standalone_midi::audio_thread::MidiAudioThreadHandler;
//! use audio_processor_standalone_midi::host::MidiHost;
//! use audio_processor_standalone_midi::vst::MidiVSTConverter;
//! use basedrop::Collector;
//!
//! // GC ======================================================================================
//! // See `audio-garbage-collector` for an easier to use wrapper on top of this.
//! //
//! // `Collector` will let us use reference counted values on the audio-thread, which will be
//! // pushed to a queue for de-allocation. You must set-up a background thread that forces it
//! // to actually collect garbage from the queue.
//! let gc = Collector::new();
//! let handle = gc.handle();
//!
//! // Host ====================================================================================
//! // A host may be created with `new` or `default_with_handle`.
//! let mut host = MidiHost::default_with_handle(&handle);
//! // It'll connect to all MIDI input ports when started
//! // host.start().expect("Failed to connect");
//! // The host will push messages onto a lock-free queue. This is a reference counted value.
//! let midi_messages_queue = host.messages().clone();
//!
//! // Audio-thread ============================================================================
//! // ...
//! // Within your audio-thread
//! // ...
//! // You'll want to share a `MidiAudioThreadHandler` between process calls as it pre-allocates
//! // buffers.
//! let mut midi_audio_thread_handler = MidiAudioThreadHandler::default();
//!
//! // On each tick you'll call collect
//! midi_audio_thread_handler.collect_midi_messages(&midi_messages_queue);
//! // You'll get the MIDI message buffer
//! let midi_messages = midi_audio_thread_handler.buffer();
//! // ^ This is a `&Vec<MidiMessageEntry>`. If you're using `audio-processor-traits`, you can
//! // pass this into any `MidiEventHandler` implementor.
//!
//! // VST interop =============================================================================
//! // If you want to interface with a VST plugin, you'll need to convert messages into the
//! // C-api.
//! // ...
//! // You'll want to share this between process calls as it pre-allocates buffers.
//! let mut midi_vst_converter = MidiVSTConverter::default();
//! midi_vst_converter.accept(&midi_messages);
//! // This can be passed into VST plugins.
//! let events: &vst::api::Events = midi_vst_converter.events();
//! }
//! ```
/// Audio-thread handling of messages
pub mod audio_thread;
/// Defaults
pub mod constants;
/// Hosting of MIDI
pub mod host;
/// VST API conversion
pub mod vst;
#[cfg(test)]
pub(crate) mod test_util;