flo™

A modern audio codec supporting both lossless and lossy compression.

• Lossless mode: Adaptive Linear Predictive Coding (ALPC) with Rice encoding (~2-3x compression)
• Lossy mode: MDCT-based psychoacoustic transform coding (~10-30x compression)

Features

• Dual-mode compression: Lossless for perfect quality, lossy for smaller files
• Lossy quality levels: Low (~48kbps), Medium (~128kbps), High (~192kbps), VeryHigh (~256kbps), Transparent (~320kbps)
• Psychoacoustic masking: Automatically discards inaudible frequencies for efficient lossy encoding
• Lossless compression with typical 2-3x compression ratios
• Mono and stereo audio support
• Multiple sample rates (44100, 48000, etc.)
• WebAssembly support for browser-based encoding/decoding
• CLI converter for converting MP3, WAV, FLAC, OGG to flo™
• Streaming decoder for real-time playback and progressive loading
• Rich metadata support (ID3v2.4 compatible + flo-unique extensions)

Compression Comparison

Mode	Quality	Typical Ratio	Equivalent Bitrate	Use Case
Lossy	Low	~30x	~48 kbps	Speech, podcasts
Lossy	Medium	~10x	~128 kbps	General music
Lossy	High	~6x	~192 kbps	Quality listening
Lossy	VeryHigh	~4x	~256 kbps	Near-transparent
Lossy	Transparent	~3x	~320 kbps	Archival
Lossless	-	~2-3x	-	Perfect quality

Quick Start

Build

# Build everything (native, CLI, WASM)
./scripts/build.sh

# Build only CLI converter
./scripts/build.sh reflo

# Build only WASM for web
./scripts/build.sh wasm

CLI Usage

# Convert MP3 to flo™ (lossless)
flo encode music.mp3 music.flo

# Convert with lossy mode (smaller file)
flo encode music.mp3 music.flo --lossy --quality high

# Lossy with bitrate target
flo encode music.mp3 music.flo --bitrate 192

# With metadata
flo encode music.mp3 music.flo --title "My Song" --artist "Artist" --album "Album"

# Convert flo™ back to WAV  
flo decode music.flo music.wav

# Show file info
flo info music.flo

# Show info with metadata
flo info music.flo --metadata

# View full metadata (human-readable)
flo metadata music.flo

# View metadata as JSON
flo metadata music.flo --json

# Validate file
flo validate music.flo

Web Demo

# Start dev server
./scripts/serve.sh

# Open http://localhost:8080

The web demo supports:

• Encoding mode selection: Toggle between lossless and lossy
• Quality slider: Choose from 5 lossy quality levels
• Generating test signals (sine wave, stereo test, white noise)
• Recording from microphone
• Uploading audio files (MP3, WAV, FLAC, OGG, etc.)
• Displaying metadata, cover art, sections, and synced lyrics
• Downloading as .flo or .wav

Metadata

flo™ supports comprehensive metadata in MessagePack format, compatible with ~80% of ID3v2.4 fields plus flo-unique extensions.

Lightning-Fast Metadata Editing

Unlike other formats where editing metadata requires:

• Re-encoding the entire file (lossy formats)
• Complex block manipulation (FLAC)
• Hope you have enough padding (MP3)

FLO's design separates metadata from audio data, allowing instant updates. No re-encoding. No quality loss. No waiting.

Standard Fields (ID3v2.4 Compatible)

Category	Fields
Identification	title, subtitle, album, track_number/total, disc_number/total, isrc
People	artist, album_artist, composer, conductor, lyricist, remixer
Properties	genre, mood, bpm, key, language
Dates	year, recording_time, release_time
Media	pictures (APIC), comments (COMM), lyrics (USLT), synced_lyrics (SYLT)

flo-Unique Extensions

Feature	Description
waveform_data	Pre-computed waveform peaks for instant visualization
section_markers	Intro/verse/chorus/bridge/outro timestamps
bpm_map	Tempo changes throughout the track
key_changes	Musical key changes with timestamps
loudness_profile	Frame-by-frame LUFS measurements
synced_lyrics	First-party SYLT support with timestamps
creator_notes	Timestamped producer/artist commentary
collaboration_credits	Detailed per-person contribution tracking
remix_chain	Track derivation/sample history
animated_cover	GIF/WebP animated artwork
cover_variants	Multiple cover versions (explicit, clean, etc.)

JavaScript API

import { encode, get_metadata, get_cover_art, get_synced_lyrics } from './libflo_audio.js';

// Create metadata
const metadata = create_metadata_from_object({
    title: "My Song",
    artist: "Artist",
    bpm: 128,
    section_markers: [
        { timestamp_ms: 0, section_type: "intro" },
        { timestamp_ms: 30000, section_type: "verse" }
    ]
});

// Encode with metadata
const floData = encode(samples, 44100, 2, 16, metadata);

// Read metadata
const meta = get_metadata(floData);
const cover = get_cover_art(floData);
const lyrics = get_synced_lyrics(floData);

File Format

The flo™ format uses:

• Magic: FLO! (0x464C4F21)
• 66-byte header with chunk offsets
• CRC32 for integrity

Encoding Modes

Lossless (ALPC):

• Frame types 1-12 indicate LPC prediction order
• Rice-coded residuals for entropy compression
• Perfect bit-for-bit reconstruction

Lossy (Transform):

• Frame type 253 indicates MDCT-based encoding
• 2048-sample blocks with 50% overlap (Vorbis window)
• Psychoacoustic model identifies masked frequencies
• Sparse RLE encoding for quantized coefficients

See flo_audio.ksy for the complete Kaitai Struct specification.

Project Structure

flo/
├── libflo/                  # Core Rust library (also builds to WASM)
│   └── src/
│       ├── core/            # Core utilities (CRC32, Rice coding, types, metadata)
│       ├── lossless/        # Lossless encoder/decoder (ALPC)
│       └── lossy/           # Lossy encoder/decoder (MDCT, psychoacoustic)
├── reflo/             # CLI converter tool
├── Demo/                    # Web demo with JS frontend
├── Examples/                # Example flo™ files
├── scripts/                 # Build and test scripts
├── .github/workflows/       # CI configuration
└── flo_audio.ksy            # Kaitai Struct specification

API

Rust

use libflo_audio::{Encoder, Decoder, LossyEncoder, QualityPreset, FloMetadata, SectionType};

// === Lossless Encoding ===
let encoder = Encoder::new(44100, 2, 16);
let flo_data = encoder.encode(&samples, &metadata)?;

// === Lossy Encoding ===
// With quality preset
let quality = QualityPreset::High.as_f32();
let mut lossy = LossyEncoder::new(44100, 2, quality);
let flo_data = lossy.encode_to_flo(&samples, &metadata)?;

// With bitrate target
let quality = QualityPreset::from_bitrate(192, 44100, 2).as_f32();
let mut lossy = LossyEncoder::new(44100, 2, quality);
let flo_data = lossy.encode_to_flo(&samples, &metadata)?;

// === Metadata ===
let mut meta = FloMetadata::new();
meta.title = Some("My Song".to_string());
meta.artist = Some("Artist".to_string());
meta.add_section(0, SectionType::Intro, None);
meta.add_section(30000, SectionType::Verse, Some("Verse 1"));

let metadata = meta.to_msgpack()?;

// Encode with metadata
let encoder = Encoder::new(44100, 2, 16);
let flo_data = encoder.encode(&samples, &metadata)?;

// Decode (auto-detects lossless vs lossy)
let decoder = Decoder::new();
let samples = decoder.decode(&flo_data)?;

JavaScript (WASM)

import init, { 
    encode, encode_lossy, encode_transform, encode_with_bitrate,
    decode, info, validate, get_metadata 
} from './pkg-libflo/libflo_audio.js';

await init();

// Lossless encoding
const floData = encode(samples, 44100, 2, 16, metadata);

// Lossy encoding with quality level (0-4)
// 0=Low, 1=Medium, 2=High, 3=VeryHigh, 4=Transparent
const floDataLossy = encode_lossy(samples, 44100, 2, 16, 2, metadata);

// Lossy encoding with continuous quality (0.0-1.0)
const floDataTransform = encode_transform(samples, 44100, 2, 16, 0.55, metadata);

// Lossy encoding with target bitrate (kbps)
const floDataBitrate = encode_with_bitrate(samples, 44100, 2, 16, 192, metadata);

// Decode (auto-detects mode)
const decoded = decode(floData);

// Get file info
const fileInfo = info(floData);
console.log(fileInfo.is_lossy, fileInfo.compression_ratio);

// Get metadata
const meta = get_metadata(floData);

Streaming Decoder (JavaScript)

For real-time playback and progressive loading:

import init, { WasmStreamingDecoder } from './pkg-libflo/libflo_audio.js';

await init();

// Create streaming decoder
const decoder = new WasmStreamingDecoder();

// Feed data incrementally (e.g., from fetch chunks)
decoder.feed(chunk1);
decoder.feed(chunk2);

// Get file info once header is parsed
const info = decoder.get_info();
console.log(`Sample rate: ${info.sample_rate}, Channels: ${info.channels}`);

// Decode frame-by-frame for streaming playback
while (true) {
    const samples = decoder.next_frame();
    if (samples === null) break;
    
    // Schedule samples for audio playback
    playAudioSamples(samples);
}

// Or decode all available data at once
const allSamples = decoder.decode_available();

// Clean up
decoder.free();

Supported Input Formats (CLI)

• WAV (via hound)
• MP3 (via symphonia)
• FLAC (via symphonia)
• OGG Vorbis (via symphonia)
• AAC/M4A (via symphonia)

License

Copyright 2026 NellowTCS

The flo™ codec is licensed under the Apache License, Version 2.0. Check LICENSE for more details.

"Trademark" Notice

"flo" and related branding are (not yet) trademarks of NellowTCS. While the flo™ codec is open-source, the name "flo" and the branding are protected (by common decency). You may not distribute modified versions of this software under the name "flo" without permission.