Added .gitignore
[camargo/neiasound.git] / README.md
1 # neiasound #
2
3 ## Introduction ##
4
5 neiasound is a Qt-style OpenAL wrapper for games. Not yet complete but already very useful.
6 It is a clean, convenient api that can be plugged directly into your main loop.
7 It comes with a (very primitive) .wav file reader, and includes [stb_vorbis](http://nothings.org/stb_vorbis/) directly in the source tree. Also supports [libsndfile](http://www.mega-nerd.com/libsndfile/).
8
9 There is also support for streaming dynamic playlists with intros and seamless looping.
10
11 ## How do I get set up? ##
12
13 The classic combination of `qmake`, `make`, and `sudo make install` works just fine. This will also generate and install `pkgconfig` files for simplifying the configuration of dependent projects.
14
15 Please look into "neiasound.pro" for configuration options.
16
17 On Android, it is compatible with the standard OpenAL Soft port, and OpenAL-MOB. I recommend OpenAL-MOB for a better experience and reduced latency. If you disable HRTFs, I suspect performance is the same or better.
18
19 ### Embedding sources in your project ###
20
21 You can also add the soures and headers to your project structure directly, building it into the executable. Please observe the requirements of the BSD license if doing so.
22
23 All you need is to add the relevant source files into your project source lists.
24 It is a good idea to cherry-pick only the nSoundStreamer implementations you actually use.
25 The Wave and stb_vorbis streams are enough in most cases, so the only hard dependencies are OpenAL itself and Qt.
26 libsndfile is optional, but it's there if you need flac or one of the many formats it supports.
27
28 Do note that this a Qt library, and the sources need to go through moc when included directly.
29
30 ## FAQ ##
31
32 **Q: Does it support MP3? Are there plans for doing so?**
33 A: No and no. MP3 is a proprietary format and the free libraries that decode it fall into a legal grey-area.
34 This is the same reason why libsndfile does not directly support it.
35 As an alternative, the OGG Vorbis format is free from patent restrictions, has a great public domain decoder implementation included in this source tree, and best of all, is technically superior to MP3 in almost every way.
36 Please consider converting your MP3's to OGG Vorbis.
37 You can also implement your own subclass of nSoundStreamer that reads MP3 files.
38 There might be a libav streamer in the future that would do that transparently, off-process, through pipes.
39
40
41 ### Who do I talk to? ###
42
43 If you run into any problems, I (lpcamargo) will be most pleased to help!