mirror of https://github.com/AxioDL/amuse.git
87 lines
2.9 KiB
Markdown
87 lines
2.9 KiB
Markdown
### Amuse {#mainpage}
|
|
|
|
**Amuse** is a real-time MIDI and SFX sequencer, with basic effects,
|
|
3D positional audio and surround-output capabilities.
|
|
|
|
The project is designed for compatibility with Audio Groups and Song data
|
|
found in PC/N64/GCN/GBA games using the *MusyX* audio engine; providing an
|
|
alternate runtime library to use for sequencing these games' audio libraries.
|
|
|
|
#### Library
|
|
|
|
The Amuse API exposes full interactivity between a client application
|
|
(game engine) and the sequencer engine. Unlike the interrupt-driven nature
|
|
of the original console implementations (where the audio chip 'requests' more
|
|
audio as needed), Amuse is entirely synchronous. This means the client must
|
|
periodically *pump* the audio engine (typically once per video frame) to keep
|
|
the OS' audio system fed.
|
|
|
|
The client must provide the implementation for allocating and mixing audio
|
|
voices, since this may drastically differ from target to target.
|
|
`amuse::IBackendVoiceAllocator` is the pure-virtual interface to implement
|
|
for this. Alternatively, if [Boo](https://github.com/AxioDL/boo) is present
|
|
in the CMake project tree, Amuse will be compiled with a backend supporting
|
|
multiple popular low-level audio APIs. Windows, OS X, and Linux all have
|
|
excellent support this way.
|
|
|
|
Here's an example usage:
|
|
|
|
```cpp
|
|
#include <amuse/amuse.hpp>
|
|
#include "MyVoiceAllocator.hpp"
|
|
#include "MyAudioGroupLoader.hpp"
|
|
|
|
int main(int argc, char* argv[])
|
|
{
|
|
/* Up to the client to implement voice allocation and mixing */
|
|
std::unique_ptr<amuse::IBackendVoiceAllocator> voxAlloc = MakeMyVoiceAllocator();
|
|
|
|
/* Application just needs one per audio output (not per channel) */
|
|
amuse::Engine snd(*voxAlloc);
|
|
|
|
/* An 'AudioGroup' is an atomically-loadable unit within Amuse.
|
|
* A client-assigned integer serves as the handle to the group once loaded
|
|
*/
|
|
amuse::IntrusiveAudioGroupData data = LoadMyAudioGroup();
|
|
snd.addAudioGroup(data);
|
|
|
|
/* Starting a SoundMacro playing is accomplished like so: */
|
|
int sfxId = 0x1337;
|
|
float vol = 1.0f;
|
|
float pan = 0.0f;
|
|
std::shared_ptr<Voice> voice = snd.fxStart(sfxId, vol, pan);
|
|
|
|
/* Play for ~5 sec */
|
|
int passedFrames = 0;
|
|
while (passedFrames < 300)
|
|
{
|
|
snd.pumpEngine();
|
|
++passedFrames;
|
|
WaitForVSync();
|
|
}
|
|
|
|
/* Stopping a SoundMacro is accomplished by sending a
|
|
* MIDI-style 'KeyOff' message for the voice
|
|
*/
|
|
voice->keyOff();
|
|
|
|
/* Play for 2 more seconds to allow the macro to gracefully fade-out */
|
|
passedFrames = 0;
|
|
while (passedFrames < 120)
|
|
{
|
|
snd.pumpEngine();
|
|
++passedFrames;
|
|
WaitForVSync();
|
|
}
|
|
|
|
/* Clean up and exit */
|
|
return 0;
|
|
}
|
|
```
|
|
|
|
#### Tool
|
|
|
|
In addition to the library, a command-line tool for performing various pipeline
|
|
tasks is provided. Compilers for audio groups and song data, as well as basic
|
|
playback functionality is available via the tool.
|