Shadowtrance
116 lines
3.7 KiB
Markdown
116 lines
3.7 KiB
Markdown
# 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
|
|
|
|
```cpp
|
|
#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
|
|
|
|
```cmake
|
|
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
|
|
|
|
```text
|
|
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](LICENSE.md).
|