Library Lua Scripts

The floe.lua file is the most important part of a Floe sample library. This page serves as documentation for all of the functions that you can use in your script to create and configure the library and its instruments.

Floe runs your script using Lua v5.4, providing you with access to these 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.

Library Functions

Use these functions to create your sample library. Take note of the [required] annotations - omitting fields marked with these 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. Keep it short and use tagline for more details. 
    -- [required]
    name = "Iron Vibrations",

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

    -- The URL for this Floe library.
    -- [optional, default: no url]
    library_url = "https://example.com/iron-vibrations",

    -- A description of the library. You can be verbose and use newlines (\n).
    -- [optional, default: no description]
    description = "A collection of resonating metal objects sampled using a handheld stereo recorder.",

    -- Who created this library. Keep it short, use the description for more 
    -- details. [required]
    author = "Found-sound Labs",

    -- URL relating to the author or their work.
    -- [optional, default: ]
    author_url = "https://example.com",

    -- 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",

    -- Specify a folder to group instruments under a common heading. It may 
    -- contain slashes to represent a hierarchy. See 
    -- https://floe.audio/develop/tags-and-folders.html for more information.
    -- [optional, default: no folders]
    folder = "Fences/Steel",

    -- A description of the instrument. Start with a capital letter an end with a 
    -- period.
    -- [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. See 
    -- https://floe.audio/develop/tags-and-folders.html for more information.
    -- [optional, default: no tags]
    tags = { "found sounds", "tonal percussion", "metal", "keys", "cold", "ambient", "IDM", "cinematic" },

    -- 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, {
    -- 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,

    -- 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 128. The start number is 
        -- inclusive, the end is exclusive.
        -- [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 start number 
        -- is inclusive, the end is exclusive.
        -- [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 with the same round_robin_sequencing_group and 
        -- trigger_event, then this region will trigger on every third press of a 
        -- key only. round_robin_index should begin at 0 and be consecutive. The 
        -- total number of round-robins is calculated automatically.
        -- [optional, default: no round-robin]
        round_robin_index = 0,

        -- Group together regions that have this same string, so that their 
        -- round_robin_index is part of a separate sequence to other 
        -- round_robin_sequencing_groups. Use this when you have multiple sets of 
        -- regions that have a different number of round-robins with the same 
        -- trigger_event.
        -- [optional, default: instrument-wide group]
        round_robin_sequencing_group = "group1",

        -- If another region in this instrument is triggered at the same time as 
        -- this one and is overlapping this, and also has this option enabled, 
        -- then both regions will play crossfaded in a proportional amount for the 
        -- overlapping area, creating a smooth transition between velocity layers. 
        -- Only works if there's exactly 2 overlapping layers.
        -- [optional, default: false]
        feather_overlapping_velocity_layers = false,

        -- For every region that has this same string, automatically set the start 
        -- and end values for each region's key range based on its root key.
        -- [optional, default: no auto-map]
        auto_map_key_range_group = "group1",
    },

    -- Loop configuration.
    -- [optional, default: defaults]
    loop = {
        -- Define a built-in loop.
        -- [optional, default: no built-in loop]
        builtin_loop = {
            -- The start of the loop in frames. Inclusive. It can be negative 
            -- meaning index the file from the end rather than the start. 
            -- [required]
            start_frame = 24,

            -- The end of the loop in frames. Exclusive. It can be negative 
            -- meaning index the file from the end rather than the start. 0 means 
            -- the end of the file. [required]
            end_frame = 6600,

            -- The number of frames to crossfade. [required]
            crossfade = 100,

            -- The mode of the loop. Must be one of: "standard" or "ping-pong".
            -- [optional, default: standard]
            mode = "standard",

            -- If true, the start, end and crossfade values cannot be overriden by 
            -- a custom loop from Floe's GUI.
            -- [optional, default: ]
            lock_loop_points = false,

            -- If true, the loop mode value cannot be overriden by a custom mode 
            -- from Floe's GUI.
            -- [optional, default: ]
            lock_mode = false,
        },

        -- The requirement for this region to loop. Must be one of: 
        -- "default" => Default looping behaviour.
        -- "always-loop" => This region will always loop - either using the built 
        -- in loop, a user defined loop, or a default built-in loop.
        -- "never-loop" => This region will never loop even if there is a 
        -- user-defined loop. Set all regions of an instrument to this to entirely 
        -- disable looping for the instrument.
        -- [optional, default: default]
        loop_requirement = "always-loop",
    },

    -- Timbre layering configuration.
    -- [optional, default: no timbre layering]
    timbre_layering = {
        -- 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 overlap this range 
        -- with other timbre layer ranges. Floe will create an even crossfade of 
        -- all overlapping sounds. The start number is inclusive, end is 
        -- exclusive. This region's velocity_range should be 0-100.
        -- [optional, default: no timbre layering]
        layer_range = { 0, 50 },
    },

    -- Audio properties.
    -- [optional, default: defaults]
    audio_properties = {
        -- Apply a gain to the audio data in decibels.
        -- [optional, default: 0]
        gain_db = -3,

        -- The number of frames to skip at the start of the audio data.
        -- [optional, default: 0]
        start_offset_frames = 0,

        -- Tune the audio data in cents.
        -- [optional, default: 0]
        tune_cents = 0,
    },

    -- Playback configuration.
    -- [optional, default: defaults]
    playback = {
        -- The requirement for keytracking. Must be one of: "default", "always" or 
        -- "never".
        -- [optional, default: default]
        keytrack_requirement = "default",
    },
})

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",

    -- Specify a folder to group IRs under a common heading. It may contain 
    -- slashes to represent a hierarchy. See 
    -- https://floe.audio/develop/tags-and-folders.html for more information.
    -- [optional, default: no folders]
    folder = "Cathedrals",

    -- An array of strings to denote properties of the IR. See 
    -- https://floe.audio/develop/tags-and-folders.html for more information.
    -- [optional, default: no tags]
    tags = { "acoustic", "cathedral" },

    -- A description of the IR. Start with a capital letter an end with a period.
    -- [optional, default: no description]
    description = "Sine sweep in St. Paul's Cathedral.",
})

floe.set_attribution_requirement

Sets the attribution information for a particular audio file or folder. It takes 2 parameters: a path to the file or folder whose license information you want to set, and a table of configuration. If the path is a folder, the attribution requirement will be applied to all audio files in that folder and its subfolders.

floe.set_attribution_requirement("Samples/bell.flac", {
    -- The title of the work. [required]
    title = "Bell Strike",

    -- Name of the license. [required]
    license_name = "CC-BY-4.0",

    -- URL to the license. [required]
    license_url = "https://creativecommons.org/licenses/by/4.0/",

    -- The name/identification of the persons or entities to attribute the work 
    -- to. [required]
    attributed_to = "John Doe",

    -- URL to the original work if possible.
    -- [optional, default: ]
    attribution_url = "https://example.com",
})

Support Function

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 },
        auto_map_key_range_group = "group1",
        feather_overlapping_velocity_regions = false,
    },
}

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

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