waver/lib.rs
1// Copyright 2019 Waver Contributors
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! # Waver: waveform generation library
16//!
17//! A waveform can be the fundamental sinusoidal wave or a complex waveform of varying
18//! frequency, phase shift or amplitude. Waver is useful where there's a need to generate
19//! a simple sinusoidal sound wave or for constructing a frequency or amplitude
20//! modulated carrier wave in bare-metal Arduino or a Raspberry Pi.
21//!
22//! ## Features
23//!
24//! * Arbitrary quantization levels. Specify the bit depth when constructing `Waveform`.
25//! * Online wave generation. No buffers, infinite iterators.
26//! * Wave superposition with weighted amplitudes.
27//! * Modulate signal's frequency, amplitude or phase.
28//! * Numerically stable, prevents clipping.
29//!
30//! ## Example
31//!
32//! ```rust
33//! use std::{vec::Vec, f32::consts::PI};
34//! use waver::{Waveform, Wave, WaveFunc};
35//!
36//! // 44.1Khz sampling rate and 16-bit depth.
37//! let mut wf = waver::Waveform::<i16>::new(44100.0);
38//!
39//! // Superpose a sine wave, a cosine wave and a triangle function.
40//! wf.superpose(Wave { frequency: 2600.0, ..Default::default() })
41//! .superpose(Wave { frequency: 2600.0, phase: PI / 2.0, ..Default::default() })
42//! .superpose(Wave { frequency: 2600.0, func: WaveFunc::Triangle, ..Default::default() })
43//! .normalize_amplitudes();
44//!
45//! // Quantization of 100 samples
46//! let _output: Vec<i16> = wf.iter().take(100).collect();
47//! ```
48
49#![cfg_attr(not(test), no_std)]
50
51extern crate alloc;
52
53mod wave;
54mod waveform;
55
56pub use wave::{Wave, WaveFunc, WaveIterator};
57pub use waveform::{Waveform, WaveformIterator};
58
59// Test README.md
60#[cfg(doctest)]
61mod readme {
62 use doc_comment::doctest;
63 doctest!("../README.md");
64}