IMPORTANT: Floe is heavily under development. This manual is a work-in-progress.

Some things may be incorrect, missing or broken. We are bit-by-bit filling in the gaps ahead of version 1.0.0.

We're working on providing more libraries for Floe. This page will be updated soon.

The preset features of Floe are under development and this page will be updated as things progress.

Developing Libraries for Floe

This document explains the details of Floe’s sample library format and how to develop libraries for it. Developing libraries for Floe does require some basic programming knowledge.

Be sure to read the About Sample Libraries page first.

Why a new format?

No existing format met our requirements for Floe, which are:

• Libraries should be plain folders of audio files.
• Libraries should be portable across filesystems & operating systems.
• Libraries should be configured using a proper programming language to enable creating complex libraries in a maintainable way.
• The format should be extensible - allowing us to innovate in the field of sampling.
• The solution should easily integrate into Floe’s codebase.

The structure

Let’s look at the structure of a Floe sample library:

📂FrozenPlain - Slow/
├── 📄slow.floe.lua
├── 📄Licence.html
├── 📄About Slow.html
├── 📁Samples/
│   ├── 📄synth_sustain_c4.flac
│   └── 📄synth_sustain_d4.flac
└── 📁Images/
    ├── 📄background.png
    └── 📄icon.png

There’s only one essential part of a Floe sample library: the floe.lua file. This file can also end with .floe.lua - for example, woodwind-textures.floe.lua.

The rest of the structure are conventions that are recommended but not required:

• Licence: Sample libraries are recommended to have a file called Licence that describes the terms of use of the library. It can be any format.
• About: A file that describes the library. Any file format. Information about a library is useful for when someone might not have Floe’s GUI available.
• Library folder name: The folder containing the floe.lua file should be named: “Developer - Library Name”.
• Subfolders: Subfolders are up to the developer. We recommend ‘Samples’ for audio files and ‘Images’ for images. These can have any number of subfolders. Your floe.lua file can reference any file in the library folder.

The floe.lua file

The floe.lua file is the most important part of a library. It’s a script that maps and configures the audio files into playable instruments, written in the Lua 5.4 programming language.

Here’s an example of a floe.lua file:

local library = floe.new_library({
    name = "Iron Vibrations",
    tagline = "Organic sounds from resonating metal objects",
    url = "https://example.com/iron-vibrations",
    description = "A collection of resonating metal objects sampled using a handheld stereo recorder.",
    author = "Found-sound Labs",
    minor_version = 1,
    background_image_path = "Images/background.jpg",
    icon_image_path = "Images/icon.png",
})

local instrument = floe.new_instrument(library, {
    name = "Metal Fence Strike",
    folders = "Fences/Steel",
    description = "Tonal pluck metallic pluck made from striking a steel fence.",
    tags = { "Pluck", "Metallic", "Organic" },
    waveform_audio_path = "Samples/file1.flac",
})

floe.add_region(instrument, {
    file = {
        path = "Samples/One-shots/Resonating String.flac",
        root_key = 60,
        loop = { 24, 6600, 100, false },
    },
    trigger_criteria = {
        trigger_event = "note-on",
        key_range = { 60, 64 },
        velocity_range = { 0, 100 },
        round_robin_index = 0,
    },
    options = {
        timbre_crossfade_region = { 0, 50 },
        auto_map_key_range_group = "group1",
        feather_overlapping_velocity_regions = false,
    },
})

floe.add_ir(library, {
    name = "Cathedral",
    path = "irs/cathedral.flac",
})

return library

This file uses Floe’s Lua API to create the library, create instruments, and add regions and impulse responses. It references the audio files in the library using relative paths.

floe.new_library() must be called and returned it at the end of the script. All other features are optional. When Floe runs your Lua file, it will show you any errors that occur along with a line number and a description.

How-to get started

1. Create a new folder in one of Floe’s sample library folders called ‘My name - My library’.
2. Create a file in that folder called my-library.floe.lua.
3. Open the Lua file in your text editor.
4. Use the floe.new_library() function to create your library, filling in all the fields marked [required] in the API reference.
5. At the end of the file, return the library object you just created.
6. Open Floe.

Creating high-quality samples

Levels

It’s important to ensure your audio samples have the the right levels. This makes browsing and switching samples in Floe a consistent, nice experience. Floe offer the ability to layer sounds together, this process is made easier for users when different instruments have similar levels.

Signet can be a useful tool for changing the levels of your samples. When changing the volume levels of a multi-sampled instrument, you probably don’t want to normalise each sample individually because part of the character of the instrument is it’s different volume levels. Instead, you could change the gain of the instrument as a whole. Signet has features for this. It also has features for proportionally moving levels towards a target level. This allows you to keep some of the character of an instrument while nudging it towards a more consistent level.

We will be updating this section with our own experience, but to get started we suggest:

• Peak levels should be less than -3 dB.
• RMS levels for an instrument as a whole should be around -18 dB. Play the instrument polyphonically and watch the RMS level. If the instrument is designed to be monophonic, then adjust for that.
• Impulse responses should have an RMS level of around -16 dB.
• The noise floor should be as low as possible: -60 dB is a good target. Use high-quality noise reduction tools to remove noise from your samples if you need to. Noise levels can quickly stack up with a multi-sampled instrument played polyphonically. Being too aggressive with algorithmic noise reduction can make your samples sound unnatural - so it’s a balance.

Sample rate, bit depth, and file format

Floe only supports FLAC and WAV files. We recommend using FLAC for your samples. It’s lossless and can reduce the file size by 50% to 70%. Floe is fast at loading FLAC files.

We find 44.1 kHz and 16-bit is often a perfectly fine choice. 48 kHz and 24-bit might be appropriate options in certain cases.

Volume envelopes of samples

If your sample is a single continuous sound, then don’t include a fade-in or fade-out in the sample. Floe has a GUI for volume envelopes that offer more control: they can be adjusted to any value, automated by the DAW, and then are independent of the playback speed of the sample. If you have a sample that is stretched across a keyboard range, it will be sped-up or slowed-down in order to be the correct pitch. If there’s a volume fade then the speed of the fade will change depending on the pitch of the voice. This is not normally a desirable effect.

If you sound has important timbral variation over time, then don’t cut that away. Only if the sound is a constant tone should you remove the fade.

Library Lua API

This document describes the functions you can use in your sample library’s floe.lua script to create and configure the library and its instruments.

Floe runs your script using Lua v5.4. You have access to some of Lua’s standard libraries: math, string, table and utf8. The other standard libraries are not available - including the require function. This is to minimise security risks.

If there are any errors in your script, Floe will show them on the GUI along with a line number and a description of the problem.

See the floe.lua section of “Develop Libraries” to see a complete example of a Floe Lua file.

Library API

Use these functions to create your sample library. Take note of the [required] annotations - omitting these fields will cause an error.

floe.new_library

Creates a new library. It takes one parameter: a table of configuration. It returns a new library object. You should only create one library in your script. Return the library at the end of your script.

The library is the top-level object. It contains all the instruments, regions, and impulse responses.

local library = floe.new_library({
    -- The name of the library. [required]
    name = "Iron Vibrations",

    -- A few words to describe the library. [required]
    tagline = "Organic sounds from resonating metal objects",

    -- The URL associated with the library.
    -- [optional, default: no url]
    url = "https://example.com/iron-vibrations",

    -- A description of the library.
    -- [optional, default: no description]
    description = "A collection of resonating metal objects sampled using a handheld stereo recorder.",

    -- The name of the creator of this library. [required]
    author = "Found-sound Labs",

    -- The minor version of this library - backwards-compatible changes are 
    -- allowed on a library; this field represents that. Non-backwards-compatibile 
    -- changes are not allowed: you'd need to create a new library such as: 
    -- "Strings 2".
    -- [optional, default: 1]
    minor_version = 1,

    -- Path relative to this script for the background image. It should be a jpg 
    -- or png.
    -- [optional, default: ]
    background_image_path = "Images/background.jpg",

    -- Path relative to this script for the icon image. It should be a square jpg 
    -- or png.
    -- [optional, default: ]
    icon_image_path = "Images/icon.png",
})

floe.new_instrument

Creates a new instrument on the library. It takes 2 parameters: the library object and a table of configuration. It returns a new instrument object. You can call this function multiple times to create multiple instruments.

An instrument is like a musical instrument. It is a sound-producing entity that consists of one or more samples (samples are specified in regions). Each library can have multiple instruments.

local instrument = floe.new_instrument(library, {
    -- The name of the instrument. Must be unique. [required]
    name = "Metal Fence Strike",

    -- Words separated by slashes used to hierarchically categorise the 
    -- instrument.
    -- [optional, default: no folders]
    folders = "Fences/Steel",

    -- A description of the instrument.
    -- [optional, default: no description]
    description = "Tonal pluck metallic pluck made from striking a steel fence.",

    -- An array of strings to denote properties of the instrument.
    -- [optional, default: no tags]
    tags = { "Pluck", "Metallic", "Organic" },

    -- Path to an audio file relative to this script that should be used as the 
    -- waveform on Floe's GUI.
    -- [optional, default: first region path]
    waveform_audio_path = "Samples/file1.flac",
})

floe.add_region

Adds a region to an instrument. It takes 2 parameters: the instrument object and a table of configuration. Doesn’t return anything. You can call this function multiple times to create multiple regions.

A region is a part of an instrument. It defines an audio file and the conditions under which it will be played. For example, you might have a region that plays the audio file Piano_C3.flac when the note C3 is played. Each instrument must have one or more regions.

floe.add_region(instrument, {
    -- The file for this region. [required]
    file = {
        -- A path to an audio file, relative to this current lua file. [required]
        path = "Samples/One-shots/Resonating String.flac",

        -- The pitch of the audio file as a number from 0 to 127 (a MIDI note 
        -- number). On a range from 0 to 127. [required]
        root_key = 60,

        -- The region of the file that can be looped. It should be an array: 3 
        -- integers and 1 boolean: { start, end, crossfade, is_ping_pong boolean 
        -- }. Note that the end number is not inclusive. The start and end numbers 
        -- can be negative meaning they index the file from the end rather than 
        -- the start. For example, -1 == number_frames_in_file, -2 == 
        -- (number_frames_in_file - 1), etc.
        -- [optional, default: no loop]
        loop = { 24, 6600, 100, false },
    },

    -- How this region should be triggered.
    -- [optional, default: defaults]
    trigger_criteria = {
        -- What event triggers this region. Must be one of: "note-on" or 
        -- "note-off".
        -- [optional, default: note-on]
        trigger_event = "note-on",

        -- The pitch range of the keyboard that this region is mapped to. These 
        -- should be MIDI note numbers, from 0 to 127. Note that the end number is 
        -- not inclusive.
        -- [optional, default: { 60, 64 }]
        key_range = { 60, 64 },

        -- The velocity range of the keyboard that this region is mapped to. This 
        -- should be an array of 2 numbers ranging from 0 to 100. The first number 
        -- represents the start of the velocity range and the second number 
        -- represents 1-past the end of the range.
        -- [optional, default: { 0, 100 }]
        velocity_range = { 0, 100 },

        -- Trigger this region only on this round-robin index. For example, if 
        -- this index is 0 and there are 2 other groups with round-robin indices 
        -- of 1 and 2, then this region will trigger on every third press of a key 
        -- only.
        -- [optional, default: no round-robin]
        round_robin_index = 0,
    },

    -- Additional options for this region.
    -- [optional, default: defaults]
    options = {
        -- The start and end point, from 0 to 100, of the Timbre knob on Floe's 
        -- GUI that this region should be heard. You should overlay this range 
        -- with other timbre_crossfade_regions. Floe will create an even crossfade 
        -- of all overlapping sounds. Note that the end number is not inclusive.
        -- [optional, default: no timbre-crossfade]
        timbre_crossfade_region = { 0, 50 },

        -- For every region that matches this group, automatically set the start 
        -- and end values for each region's key range based on its root key. Only 
        -- works if all region's velocity range are the same.
        -- [optional, default: no auto-map]
        auto_map_key_range_group = "group1",

        -- If another region is triggered at the same time as this one and is 
        -- overlapping this, then both regions will play crossfaded together. This 
        -- smooths the transitions between velocity layers.
        -- [optional, default: false]
        feather_overlapping_velocity_regions = false,
    },
})

floe.add_ir

Adds an reverb impulse response to the library. It takes 2 parameters: the library object and a table of configuration. Doesn’t return anything. You can call this function multiple times to create multiple impulse responses.

floe.add_ir(library, {
    -- The name of the IR. Must be unique. [required]
    name = "Cathedral",

    -- File path to the impulse response file, relative to this script. [required]
    path = "irs/cathedral.flac",
})

Support API

Floe provides some additional functions to make developing libraries easier.

floe.extend_table

Extends a table with another table, including all sub-tables. It takes 2 parameters: the base table and the table to extend it with. The base table is not modified. The extension table is modified and returned. It has all the keys of the base table plus all the keys of the extended table. If a key exists in both tables, the value from the extension table is used.

Floe doesn’t have the concept of ‘groups’ like other formats like SFZ or Kontakt have. Instead, this function offers a way to apply a similar configuration to multiple regions. Alternatively, you can use functions and loops in Lua to add regions in a more dynamic way.

local group1 = {
    trigger_criteria = {
        trigger_event = "note-on",
        velocity_range = { 0, 100 },
    },
    options = {
        auto_map_key_range_group = "group1",
        feather_overlapping_velocity_regions = false,
    },
}

floe.add_region(instrument, floe.extend_table(group1, {
    file = {
        path = "One-shots/Resonating String 2.flac",
        root_key = 65,
    },
}))

floe.add_region(instrument, floe.extend_table(group1, {
    file = {
        path = "One-shots/Resonating String 3.flac",
        root_key = 68,
    },
}))

Develop Preset Packs

Developing preset packs is simply a matter of saving preset files into a folder and then packaging them into a Floe Package. Packages can can contain libraries and/or presets.

Package libraries & presets for distribution

The easiest and most reliable way to distribute your Floe sample libraries and presets is with Floe Packages.

Floe Packages are ZIP files that contain Floe sample libraries and/or presets. These are the files that users will download and use to install new libraries and presets into Floe.

Floe offers an easy-to-use GUI for installing these Packages. This installation process carefully considers the user’s existing libraries and presets, their versions, their installation preferences, even whether their installed libraries have been modified or not. The result is something that should ‘just work’ or at least provide clear instructions on what to do next.

As with Floe’s sample library format, openness is key. That’s why Floe Packages are just normal ZIP files with a specific structure. Anyone can create them and anyone can open them. Additionally, it gives the user the option to extract them manually rather than use Floe’s GUI if they wish.

Create Floe Packages using our command-line tool or any ZIP program.

Packager command-line tool

We recommend using our command-line tool to create Floe Packages. It ensures everything is set up correctly and adds a couple of nice-to-have features, particularly for users who want to install the package manually rather than with Floe’s GUI.

However, you can use any ZIP program to create Floe Packages. Just make sure they follow the structure described in the next section.

Download packager

Floe Packager Windows: Download Floe-Packager-v0.0.2-Windows.zip (1 MB)

Floe Packager macOS: Download Floe-Packager-v0.0.2-macOS.zip (1 MB)

Download the program, extract it, and run it from the command line.

Usage

Here’s the output of floe-packager --help:

Takes libraries and presets and turns them into a Floe package file (floe.zip).
You can specify multiple libraries and preset-folders. Additionally:
- Validates any Lua files.
- Ensures libraries have a License file.
- Generates an 'About' HTML file for each library.
- Embeds a checksum file into the package for better change detection if the package
  is installed manually.

Usage: floe-packager [ARGS]

Optional arguments:
  --library-folders <path>...     One or more library folders
  --presets-folders <path>...     One or more presets folders
  --output-package-folder <path>  Folder to write the created package to
  --package-name <name>           Package name - inferred from library name if not provided

Examples

These examples use bash syntax.

# Creates a Floe Package from the Slow library and the Slow Factory Presets.
# Slow and "Slow Factory Presets" are folders in the current directory.
./floe-packager --library-folders "Slow" \
                --preset-folders "Slow Factory Presets" \
                --output-folder .

# Creates a Floe Package containing multiple libraries and no presets
./floe-packager --library-folders "C:/Users/Sam/Floe-Dev/Strings" \
                                "C:/Users/Sam/Floe-Dev/Common-IRs" \
                --output-folder "C:/Users/Sam/Floe-Dev/Releases" \
                --package-name "FrozenPlain - Strings"

Packager structure

If you’re not using the packager tool, you need to know the structure of the Floe Package. It’s very simple.

Requirements of a floe package:

• The filename must end with .floe.zip
• The ZIP must contain a folder called Libraries and/or a folder called Presets. If present, these folders must contain the libraries and presets respectively.

Be careful that your ZIP program is not adding an extra folder when you create the ZIP file. There should not be a top-level folder in the ZIP file, just the Libraries and/or Presets folders.

Example: single library & factory presets

📦FrozenPlain - Arctic Strings.floe.zip/
├── 📁Libraries
│   └── 📁Arctic Strings
│       ├── 📄arctic-strings.floe.lua
│       ├── 📁Samples
│       │   ├── 📄strings_c4.flac
│       │   └── 📄strings_d4.flac
│       └── 📁Images
│           ├── 📄background.png
│           └── 📄icon.png
└── 📁Presets
    └── 📁Arctic Strings Factory
        ├── 📁Realistic
        │   ├── 📄Octaved.floe-preset
        │   └── 📄Soft.floe-preset
        └── 📁Synthetic
            ├── 📄Bright.floe-preset
            └── 📄Warm.floe-preset

Example: multiple libraries

📦Audioata - Synthwave Bundle.floe.zip/
├── 📁Libraries
│   ├── 📁Synthwave Bass
│   │   ├── 📄synthwave-bass.floe.lua
│   │   └── 📁Samples
│   │       ├── 📄bass_c1.flac
│   │       └── 📄bass_d1.flac
│   ├── 📁Synthwave Drums
│   │   ├── 📄synthwave-drums.floe.lua
│   │   └── 📁Samples
│   │       ├── 📄kick.flac
│   │       └── 📄snare.flac
│   └── 📁Synthwave Synths
│       ├── 📄synthwave-synths.floe.lua
│       └── 📁Samples/
│           ├── 📄synth_c4.flac
│           └── 📄synth_d4.flac
└── 📁Presets
    └── 📁Synthwave Factory
        ├── 📄Clean.floe-preset
        ├── 📄Dirty.floe-preset
        ├── 📄Big.floe-preset
        ├── 📄Small.floe-preset
        ├── 📄Bright.floe-preset
        └── 📄Warm.floe-preset

Changelog

0.0.2

• Fix Windows installer crash
• Don’t show a console window with the Windows installer
• Better logo for Windows installer
• Remove unecessary ‘Floe Folders’ component from macOS installer

0.0.1

This is the first release of Floe. It’s ‘alpha quality’ at the moment - there will be bugs and there are a couple of missing features. This release is designed mostly to test our release process.

This release only contains the CLAP plugin. The VST3 and AU plugins will be released soon.

Mirage

Floe used to be called Mirage. Mirage contained many of the same features seen in Floe v0.0.1. But there are large structural changes, and some new features and improvements:

• Use multiple different libraries in the same instance.
• CLAP version added - VST3 and AU coming soon, VST2 support dropped.
• New installer: offline, no account/download-tickets needed. Libraries are installed separately.
• Ability for anyone to develop sample libraries using new Lua-based sample library format. The new format features a new system to tag instruments and libraries. Changes to the format are instantly applied to Floe.
• New comprehensive documentation.
• Floe settings are saved in a more robust way avoiding issues with permissions/missing files.
• Improved default locations for saving libraries and presets to avoid permissions issues.
• New settings GUI.
• Floe now can have multiple library and preset folders. It will scan all of them for libraries and presets. This is a more robust and flexible way to manage assets rather than trying to track individual files.
• Floe packages: a robust way to install libraries and presets. Floe packages are zip files in a particular layout that contain libraries and presets. In the settings of Floe, you can install these packages. It handles all the details of installing/updating libraries and presets. It checks for existing installations and updates them if needed. It even checks if the files of any existing installation have been modified and will ask if you want to replace them. Everything just works as you’d expect.
• New format for saving presets and DAW state - smaller and faster than before and allows for more expandability.

Technical changes:

• Huge refactor of the codebase to be more maintainable and expandable. There’s still more to be done yet though.
• New build system using Zig; cross-compilation, dependency management, etc.
• Comprehensive CI/CD pipeline for testing and creating release builds.
• New ‘sample library server’, our system for providing libraries and audio files to Floe in a fast, async way.