1Hound
2=====
3A wav encoding and decoding library in Rust.
4
5[![Crates.io version][crate-img]][crate]
6[![Changelog][changelog-img]](changelog.md)
7[![Documentation][docs-img]][docs]
8
9Hound can read and write the WAVE audio format, an ubiquitous format for raw,
10uncompressed audio. The main motivation to write it was to test
11[Claxon][claxon], a FLAC decoding library written in Rust.
12
13Examples
14--------
15The following example renders a 440 Hz sine wave, and stores it as a mono wav
16file with a sample rate of 44.1 kHz and 16 bits per sample.
17
18```rust
19use std::f32::consts::PI;
20use std::i16;
21use hound;
22
23let spec = hound::WavSpec {
24    channels: 1,
25    sample_rate: 44100,
26    bits_per_sample: 16,
27    sample_format: hound::SampleFormat::Int,
28};
29let mut writer = hound::WavWriter::create("sine.wav", spec).unwrap();
30for t in (0 .. 44100).map(|x| x as f32 / 44100.0) {
31    let sample = (t * 440.0 * 2.0 * PI).sin();
32    let amplitude = i16::MAX as f32;
33    writer.write_sample((sample * amplitude) as i16).unwrap();
34}
35```
36
37The file is finalized implicitly when the writer is dropped, call
38`writer.finalize()` to observe errors.
39
40The following example computes the root mean square (RMS) of an audio file with
41at most 16 bits per sample.
42
43```rust
44use hound;
45
46let mut reader = hound::WavReader::open("testsamples/pop.wav").unwrap();
47let sqr_sum = reader.samples::<i16>()
48                    .fold(0.0, |sqr_sum, s| {
49    let sample = s.unwrap() as f64;
50    sqr_sum + sample * sample
51});
52println!("RMS is {}", (sqr_sum / reader.len() as f64).sqrt());
53```
54
55Features
56--------
57
58|                 | Read                                                    | Write                                   |
59|-----------------|---------------------------------------------------------|-----------------------------------------|
60| Format          | `PCMWAVEFORMAT`, `WAVEFORMATEX`, `WAVEFORMATEXTENSIBLE` | `PCMWAVEFORMAT`, `WAVEFORMATEXTENSIBLE` |
61| Encoding        | Integer PCM, IEEE Float                                 | Integer PCM, IEEE Float                 |
62| Bits per sample | 8, 16, 24, 32 (integer), 32 (float)                     | 8, 16, 24, 32 (integer), 32 (float)     |
63
64Contributing
65------------
66Contributions in the form of bug reports, feature requests, or pull requests are
67welcome. See [contributing.md](contributing.md).
68
69License
70-------
71Hound is licensed under the [Apache 2.0][apache2] license. It may be used in
72free software as well as closed-source applications, both for commercial and
73non-commercial use under the conditions given in the license. If you want to
74use Hound in your GPLv2-licensed software, you can add an [exception][exception]
75to your copyright notice. Please do not open an issue if you disagree with the
76choice of license.
77
78[crate-img]:     https://img.shields.io/crates/v/hound.svg
79[crate]:         https://crates.io/crates/hound
80[changelog-img]: https://img.shields.io/badge/changelog-online-blue.svg
81[docs-img]:      https://img.shields.io/badge/docs-online-blue.svg
82[docs]:          https://docs.rs/hound
83[claxon]:        https://github.com/ruuda/claxon
84[apache2]:       https://www.apache.org/licenses/LICENSE-2.0
85[exception]:     https://www.gnu.org/licenses/gpl-faq.html#GPLIncompatibleLibs
86