README.md
1# lewton
2
3[](https://docs.rs/crate/lewton)
4[](https://crates.io/crates/lewton)
5[](https://deps.rs/repo/github/rustaudio/lewton)
6
7Vorbis decoder written in pure Rust.
8
9To give the decoder a try, you can do:
10```sh
11cargo run --example player /path/to/your/audio_file.ogg
12```
13It will then play back the audio.
14
15If you want to know how to use this crate, look at the examples folder.
16
17This crate has a low level API for per-packet decoding in the `audio` and `header` modules,
18and a high level API for ogg/vorbis streams in the `inside_ogg` module.
19
20Some parts were created with help from the public domain
21[stb_vorbis](http://nothings.org/stb_vorbis/) decoder implementation.
22
23The minimum required Rust version is 1.36.
24
25## Use of unsafe
26
27The entire library uses not a single line of unsafe code.
28In fact, lib.rs contains the `#![forbid(unsafe_code)]` directive.
29
30## About the history of this crate
31
32I've started started to work on this crate in December 2015.
33The goal was to learn more about Rust and audio processing,
34while also delivering something useful to the Rust ecosystem.
35
36I've tried not to look into the libvorbis implementation,
37as then I'd have to first abide the BSD license, and second
38as I didn't want this crate to become "just" a translation
39from C to Rust. Instead I wanted this crate to base on the
40spec only, so that I'd learn more about how vorbis worked.
41
42The only time I did look into the libvorbis implementation
43was to look up the implementation of a function needed by
44the ogg crate (the CRC function), which is why that crate
45is BSD licensed, and attributes the authors.
46This crate however contains no code, translated or
47otherwise, from the libvorbis implementation.
48
49After some time I realized that without any help of a working
50implementation progress would become too slow.
51
52Therefore, I've continued to work with the public domain
53`stb_vorbis` implementation and used some of its
54code (most prominently for the imdct algorithm) to
55translate it to rust. I've also used it for debugging by
56comparing its outputs with mine.
57
58Most of this crate however was created by reading the spec
59only.
60
61## Use from C
62**lewton** provides a C-compatible set of library, header and pkg-config file.
63
64To build and install it you can use [cargo-c](https://crates.io/crates/cargo-c):
65
66```sh
67cargo install cargo-c
68cargo cinstall --release --destdir /tmp/lewton
69sudo cp -a /tmp/lewton/* /
70```
71
72## License
73
74Licensed under Apache 2 or MIT (at your option). For details, see the [LICENSE](LICENSE) file.
75
76All examples inside the `examples/` folder are licensed under the
77[CC-0](https://creativecommons.org/publicdomain/zero/1.0/) license.
78
79### License of your contributions
80
81Unless you explicitly state otherwise, any contribution intentionally submitted for
82inclusion in the work by you, as defined in the Apache-2.0 license,
83shall be dual licensed / CC-0 licensed as above, without any additional terms or conditions.
84
){kind=link}
){kind=link}
){kind=link}