sfizz-unity

KO | EN

gitlite — search

#php #javascript #python #ruby #dotfiles #erlang #vim #library #wordpress #bootstrap #cli #ocaml-library

★ 13 Open GitHub ↗

A Unity3D MIDI player with instruments defined in sfz format, using sfizz as the underlying sampler.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# :musical_keyboard: sfizz-unity
[![openupm](https://img.shields.io/npm/v/dev.f1yingbanana.sfizz-unity?label=openupm&registry_uri=https://package.openupm.com)](https://openupm.com/packages/dev.f1yingbanana.sfizz-unity/)
![Twitter Follow](https://img.shields.io/twitter/follow/f1yingbanana?style=social)

Sfizz for Unity is a wrapper around [**sfizz**](https://github.com/sfztools/sfizz) - an open source audio synthesizer capable of loading virutal instruments in [**sfz**](https://sfzformat.com/) files and generating audio with them live in Unity.

This Unity wrapper takes advantage of the exported C APIs in [**sfizz.h**](https://github.com/sfztools/sfizz/blob/0eceacee861ee9328f07e8672ded3f79f792441e/src/sfizz.h), and hides the details of making function calls to C++. In addition, this package also comes with a simple audio player which interacts with the audio synthesizer. This player takes care of feeding in audio instructions (either generated by the UI or from a MIDI file) to the native library, then converting the returned buffers to a streaming [`AudioClip`](https://docs.unity3d.com/ScriptReference/AudioClip.html).

As this is a wrapper for sfizz, users need to obtain their own sfizz library (see [section](#getting-sfizz) below). Note each target platform will require a specific library built on that platform, and once placed in Unity, the library must be configured accordingly (see [plugins](https://docs.unity3d.com/Manual/Plugins.html)).

## :musical_score: System requirements
Unity 2018.4.0 or later versions. Works on:
* Windows
* macOS
* Linux
* iOS

## :control_knobs: Installation
The package is available on the [openupm registry](https://openupm.com/packages/dev.f1yingbanana.sfizz-unity/).
```
openupm add dev.f1yingbanana.sfizz-unity
```
You can also install this [via Unity Package Manager](https://docs.unity3d.com/Manual/upm-ui-giturl.html) with the following git url:
```
https://github.com/f1yingbanana/sfizz-unity.git#upm
```
An Asset Store package is in the works.

## :notes: Getting Started
### <a name="getting-sfizz"></a> :microphone: Getting sfizz
The [**sfizz**](https://github.com/sfztools/sfizz) library must be built on each of the Unity project's target platform. On Windows, we are looking for the **sfizz.dll** file. On iOS/macOS, we are looking for **sfizz.dylib**. On Linux, **sfizz.so**. Currently their releases on GitHub do not contain library files we need, so we can either build it ourselves (locally or cloning then using GitHub CI), or ask in their Discord channel (they are very nice and helpful :innocent:).

See [this fork](https://github.com/f1yingbanana/sfizz/actions/runs/1810391665) for an example of building it on GitHub for Windows (x86 and x64).

### :accordion: Importing sfizz
Once we obtained the library files, import them into Unity and set them up following [this guide](https://docs.unity3d.com/Manual/PluginInspector.html). **sfizz-unity** is a native plugin, by the way.

### :violin: Getting virtual instruments
There are plenty of free samples online, notably the [Salamander Grand Piano](https://archive.org/details/SalamanderGrandPianoV3), a copy of which is included in this package's [piano sample scene](https://github.com/f1yingbanana/sfizz-unity/tree/master/Packages/sfizz-unity/Samples/Piano). For an in-depth discussion of where to place them, see [this section below](#the-path-problem).

### :drum: Walkthrough
The class `SfizzPlayer` takes care of a lot of boilerplate code. It keeps an instance of `Sfizz` and converts audio output from it on `Update` and fills an `AudioClip` for the `AudioSource` to play. It also takes care of keeping and resizing buffers for data and latency elimination.

To use it, simply add it as a component to a `GameObject` in the scene. We now need to create a script to tell it to load an instrument and also what to play.

```C#
using F1yingBanana.SfizzUnity;
using UnityEngine;

public class MusicController : MonoBehaviour {
  // Don't forget to link the reference to the SfizzPlayer in the scene!
  public SfizzPlayer player;
  public string sfzPath;
  
  private void Start() {
    player.Sfizz.Load(sfzPath);
  }
  
  private void Update() {
    player.Sfizz.SendNoteOn(/* delay= */ 0, /* noteNumber= */ 60, /* velocity= */ 64);
  }
}
```

Add the `MusicController` component to a `GameObject` in the scene and link the `sfzzPlayer`. For `sfzPath`, enter the absolute path to your downloaded sfz file for now (more on this [below](#the-path-problem)).

Press play, and you should hear the middle C being triggered repeatedly.

For a more sophisticated setup, import the piano sample scene in the Package Manager and look at the [`PianoController`](https://github.com/f1yingbanana/sfizz-unity/blob/master/Packages/sfizz-unity/Samples/Piano/PianoController.cs).

## :guitar: Under the hood
At a high level, the **sfizz** engine tracks audio events - when a note has started or stopped. It then processes these events in batch to produce a buffer of audio data, and clears all the events. The cycle then repeats. There are some subtle differences between the C++ implementation and the C# wrapper, however. These are listed below.

### :saxophone: <a name="the-path-problem"></a> The path problem
**sfizz** expects a directory system when loading instrument audio from files, but in builds, Unity packs all used assets tightly together into bundles. This means while everything works in the Unity editor, on any standalone player it is no longer possible for **sfizz** to find the audio samples. Depending on your needs, there are two solutions.

#### My sfz files should be bundled in my application
Use the [StreamingAssets folder](https://docs.unity3d.com/Manual/StreamingAssets.html). Put your sfz file in `Assets/StreamingAssets/.../instrument.sfz`. In your controller script, pass in a global path.
```
string path = Path.GetFullPath(Path.Combine(Application.streamingAssetsPath, ".../instrument.sfz"));
sfizzPlayer.Sfizz.Load(path);
```

#### My sfz files are downloaded
Use the [persistent data path](https://docs.unity3d.com/ScriptReference/Application-persistentDataPath.html). At runtime, extract your files to the persistent data path, create your own directories, then pass in the global path.

## :banjo: FAQs
### Can I use this on Android?
No. You can try to build the source code for **Sfizz** with NDK in [this guide](https://kvurd.com/blog/compiling-a-cpp-library-for-android-with-android-studio/). StreamingAssets folder also doesn't work for Android, so you will need a system to extract the audio files to persistentDataPath instead.

### I'm getting an `EntryPointNotFoundException`, what do I do?
You likely have an incompatible sfizz library. Currently this wrapper requires a minimum version of Sfizz 1.2, and if your library is a lower version, you might get this exception. See [section](#getting-sfizz) to obtain the latest version.

### I want to use a function in **sfizz.h**, but it's not in the wrapper
This is likely because porting the function to C# is difficult. Almost all functions in the interface present in Sfizz 1.2 are in the wrapper, but if one that should be in the wrapper is missing, file a feature request.

sfizz-unity

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README