tactility_apps/Libraries/SfxEngine

SfxEngine Library

Lightweight SFX-only audio engine for ESP32/Tactility apps. A stripped-down alternative to SoundEngine (~1.5KB RAM vs ~66KB).

Features

• 4 voices with polyphonic mixing
• 9 waveforms: Square, Pulse (25%/12.5%/75%), Triangle, Sawtooth, Sine, Noise, RetroNoise
• ADSR envelope + special types (Punch, Flare, Swell, Twang, Decay)
• Effects: Vibrato, Pitch Sweep, Polyphonic Gate, Auto-Normalization
• 52 curated SFX: UI sounds, pet sounds, game sounds, drums, percussion, effects, jingles
• Thread-safe queue-based API
• ESP32 optimized: ~1.5KB RAM, heap-allocated

When to Use

	SfxEngine	SoundEngine
RAM	~1.5KB	~66KB
Voices	4	8
SFX	52 curated	100+
BGM	No	Yes (9 tracks)
Synthesis	Basic	FM, Filter, Pluck, Drums
Effects	Vibrato, Sweep, Gate, Norm	+ Delay, Tremolo, Arp, Bitcrush
Use case	UI feedback, simple games	Rich audio, music apps

Quick Start

#include "SfxEngine.h"

SfxEngine* engine = new SfxEngine();

if (!engine->start()) {
    ESP_LOGE(TAG, "Failed to start SfxEngine");
    return;
}
engine->play(SfxId::Coin);                // Predefined SFX
engine->playNote(0, 60, 200);             // Manual: voice 0, C4, 200ms

engine->stop();
delete engine;

Available SFX

UI (9): Click, Confirm, Cancel, Error, MenuOpen, MenuClose, Toggle, Slider, Tab TamaTac Pet (8): Feed, Play, Medicine, Sleep, Clean, Evolve, Sick, Death Game (11): Coin, Powerup, Jump, Land, Laser, Explosion, Hurt, Warp, Pickup, OneUp, BrickHit Notifications (3): Alert, Notify, Success Drums (4): Kick, Snare, HiHat, Crash Synth Percussion (5): SynthKick, SynthSnare, SynthHat, SynthTom, SynthRim Effects (10): Zap, Blip, Chirp, Whoosh, Ding, RisingWhoosh, FallingWhoosh, GlitchHit, DigitalBurst, RetroBell Jingles (2): LevelUp, GameOver

CMake Integration

file(GLOB_RECURSE SOURCE_FILES Source/*.c*)
file(GLOB_RECURSE SFX_ENGINE_FILES ../../../Libraries/SfxEngine/Source/*.c*)

idf_component_register(
    SRCS ${SOURCE_FILES} ${SFX_ENGINE_FILES}
    INCLUDE_DIRS
        ../../../Libraries/TactilityCpp/Include
        ../../../Libraries/SfxEngine/Include
    REQUIRES TactilitySDK esp_driver_i2s esp_driver_gpio
)

API Reference

Lifecycle

• bool start() - Start audio engine
• void stop() - Stop audio engine
• bool isRunning() - Check status

SFX

• void play(SfxId) - Play predefined sound
• void stopAllSounds() - Stop all voices

Manual Notes

• void playNote(voice, midiNote, durationMs, wave, volume) - Play custom note
• void stopVoice(voice) - Stop specific voice

Settings

• void setEnabled(bool) - Mute/unmute

Loudness is controlled by the system output volume (set via the audio_stream device / Settings UI), not by SfxEngine itself -- a fixed app-side gain on top of hardware attenuation gets swamped at low system volumes, so there's no separate volume control here.

Mixing (consistent with SoundEngine)

• void setPolyphonicGateEnabled(bool) - Soft gate when multiple voices clip (default: on)
• void setSoftGateThreshold(float) - Gate threshold 0.5-1.0 (default: 0.95)
• void setAutoNormalization(bool) - RMS-based auto-gain (default: on)
• void setTargetRms(float) - Target RMS level 0.1-0.8 (default: 0.35)
• void setRmsSmoothing(float) - Smoothing factor 0.9-0.99999 (default: 0.999)

File Structure

Libraries/SfxEngine/
  Include/
    SfxEngine.h        # Core engine header
    SfxDefinitions.h   # 52 curated SFX definitions
  Source/
    SfxEngine.cpp      # Implementation
  LICENSE.md           # GPL v3
  README.md

License

Licensed under the GNU General Public License v3.0.