1[![Build Status](https://travis-ci.org/oamldev/oaml.svg)](https://travis-ci.org/oamldev/oaml.svg?branch=master)
2[![License](http://img.shields.io/:license-mit-blue.svg)](http://doge.mit-license.org)
3
4### Open Adaptive Music Library
5
6OAML is a library the makes it easy to implement adaptive music in games.
7
8
9### First, what is adaptive music on video games?
10
11Adaptive music, also known as interactive music or dynamic music, is music that reacts to what's happening on the video game. For example, if there is a battle going on, music will get more tense to stimulate the player's reaction to the battle. There is a nice paper on the subject written by David Vink that can be found on gamecareerguide ([link](http://www.gamecareerguide.com/features/768/student_thesis_adaptive_music_for_.php?print=1)).
12
13
14### How does it work?
15
16OAML uses short music loops to make music less linear and more interactive with the player.
17
18In OAML there are three basic types of short loops:
19
20- Intro loops, played when the track starts.
21- Main loops, this is what OAML will keep playing when there is no condition triggered (actually these main loops can have one condition that is OAML_CONDID_MAIN_LOOP, check the msnake_oaml demo for more info on how it works).
22- Conditional loops, these loops are defined by a condition, based on the data provided for the condition (id, type and values) OAML will play them when these conditions meet, for example, when enemies are engaged a condition can be triggered and music will play loops that get more intense.
23
24Note that a track is only required to have one main loop at least, all the other loops are optional.
25
26
27### Supported audio formats
28
29Supports the following audio formats:
30- ogg
31- wav
32- aif
33
34
35### Supported game engines
36- Unity3d
37- Godot: [oamlGodotModule](https://github.com/oamldev/oamlGodotModule)
38
39
40### Demos
41
42Demos page: [https://oamldev.github.io/demos/](https://oamldev.github.io/demos/)
43
44
45### How to compile
46
47First install libogg and libvorbis, if you don't have them already, [https://www.xiph.org/downloads/](https://www.xiph.org/downloads/).
48
49On Linux and OSX:
50
51```
52	mkdir build
53	cd build
54	cmake ..
55	make
56	sudo make install
57```
58
59On Windows with Visual Studio check the folder 'vs'.
60
61
62### Usage
63
64Example of basic usage in C++:
65
66```C++
67{
68	// Defined somewhere in your code
69	oamlApi *oaml;
70
71	// Initialization, oaml.defs is the definitions saved/export with oamlStudio
72	oaml = new oamlApi();
73	oaml->Init("oaml.defs");
74
75	// Play a track
76	oaml->PlayTrack("track1");
77
78	// Pause music
79	oaml->Pause();
80
81	// Resume music
82	oaml->Resume();
83
84	// Stop music
85	oaml->StopPlaying();
86
87	// Shutdown OAML
88	oaml->Shutdown();
89	delete oaml;
90}
91```
92
93To create the oaml.defs file check [oamlStudio](https://github.com/oamldev/oamlStudio).
94
95
96### Exporting music for OAML
97
98When exporting music from your DAW to use with OAML the key to make the loops work seamlessly is to **enable the tail on export**.
99For now since resampling is not implemented in OAML you need to export the music in the same sample rate that your project is going to use, for example if your project uses 44100hz export all your music in 44100hz as well.
100
101
102### Notes
103
104- If you're using OAML on your project or you're interested to do so and need some help contact me.
105- Got any question? Write me an email to <marcelo@marcelofernandezmusic.com>.
106
107
108### TODO
109
110- Make the possibility that tension will not simply change to a condition loop but instead that both loops (main loop and conditional loop) will play together based on the tension percent, need to test it first.
111- Add a function for playing SFX's with a 3d position.
112- Add a loudness effect, and a reverb effect as well.
113- Implement OAML in more game engines, love2d, etc.
114
115
116### Games using OAML
117
118- [https://github.com/Andrettin/Wyrmgus](https://github.com/Andrettin/Wyrmgus)
119- [https://shawyadventures.github.io/](https://shawyadventures.github.io/)
120
121
122### About
123
124Copyright (c) 2015-2018 Marcelo Fernandez <marcelo@marcelofernandezmusic.com>
125