📦 Resource Management - Gestión de Assets Externos¶

📋 Descripción¶

El Resource Management System gestiona todos los assets externos referenciados por presets (samples, wavetables, impulse responses, lookup tables, etc.). Proporciona resolución inteligente con fallbacks, caching eficiente, y preloading estratégico.

Criticidad: ⭐⭐⭐⭐⭐ (Crítico - presets sin recursos no funcionan)

🎯 Objetivos¶

Resource Resolution: Resolver referencias a recursos con múltiples estrategias
Intelligent Caching: Cache LRU con límites de memoria configurables
Fallback System: Buscar recursos alternativos cuando faltan originales
Preloading: Cargar recursos críticos anticipadamente
Similarity Matching: Encontrar recursos similares automáticamente
Cloud Integration: Descargar recursos desde CDN cuando sea necesario

🏗️ Arquitectura¶

Componentes Principales¶

Resource Management System
│
├── ResourceRef (from PresetSchema)
│   ├── LocationType (Embedded, Relative, Absolute, Cloud)
│   ├── Path (filesystem or URL)
│   ├── Checksum (SHA256 for verification)
│   └── Metadata (size, type, fallback)
│
├── ResourceResolver
│   ├── resolve() - Main resolution entry point
│   ├── resolveEmbedded()
│   ├── resolveRelative()
│   ├── resolveAbsolute()
│   ├── resolveCloud()
│   └── findSimilar() - Similarity matching
│
├── ResourceCache
│   ├── LRU eviction policy
│   ├── Memory limit (default 2GB)
│   ├── get() / put()
│   ├── preload()
│   └── Statistics tracking
│
├── ResourceScanner
│   ├── scanDirectory() - Index resources
│   ├── buildDatabase() - Create search index
│   └── findByChecksum() - Fast lookup
│
└── ResourceManager (orchestrator)
    ├── loadResource()
    ├── cacheResource()
    ├── preloadResources()
    └── findSimilarResource()

Resource Location Types¶

1. Embedded

{
  "type": "sample",
  "location_type": "embedded",
  "path": "data:audio/wav;base64,UklGRi4AAABXQVZFZm10...",
  "size_bytes": 44100
}

- Data embedded directly in preset - No external file needed - Larger preset file size

2. Relative

{
  "type": "wavetable",
  "location_type": "relative",
  "path": "./wavetables/saw_rich.wav",
  "checksum": "sha256:abc123...",
  "fallback_path": "./wavetables/saw_basic.wav"
}

- Path relative to preset file - Portable preset bundles - Fallback if not found

3. Absolute

{
  "type": "impulse_response",
  "location_type": "absolute",
  "path": "C:/AudioLab/Resources/IR/plate_reverb.wav",
  "checksum": "sha256:def456..."
}

- Absolute filesystem path - System-specific - Fast access

4. Cloud

{
  "type": "sample",
  "location_type": "cloud",
  "path": "https://cdn.audiolab.com/samples/kick_808.wav",
  "checksum": "sha256:ghi789...",
  "size_bytes": 22050
}

- Download from CDN - Cached locally after download - Requires internet

🔄 Resolution Pipeline¶

Resolution Flow¶

1. Check Cache
   ├─ Hit  → Return cached resource
   └─ Miss → Continue to resolution

2. Determine Location Type
   ├─ Embedded  → Extract from preset
   ├─ Relative  → Search relative to preset
   ├─ Absolute  → Load from absolute path
   └─ Cloud     → Download from URL

3. Verify Checksum
   ├─ Match    → Success
   └─ Mismatch → Try fallback

4. Fallback Strategy (if resource not found)
   ├─ Try fallback_path (if specified)
   ├─ Search by checksum in database
   ├─ Find similar resource (by name/type)
   └─ Use default placeholder

5. Cache Result
   └─ Store in cache for future use

Code Example¶

// Load resource
auto resource_ref = preset.getResourceRef("sample_kick");
auto resource = resource_manager.loadResource(resource_ref);

// Resolution happens automatically
if (resource.isValid()) {
    // Use resource
    audio_engine.loadSample(resource.getData());
} else {
    // Resource not found, fallback applied
    std::cerr << "Resource not found, using fallback\n";
}

💾 Cache System¶

LRU Cache¶

Features: - Least Recently Used (LRU) eviction policy - Configurable memory limit (default: 2GB) - Per-resource type limits - Preload hints for frequently used resources

API:

ResourceCache cache(2_GB);  // 2GB limit

// Get resource (may load if not cached)
auto resource = cache.get(resource_ref);

// Preload resources
cache.preload({
    "factory_presets/*",
    "user_favorites/*"
});

// Statistics
auto stats = cache.getStatistics();
std::cout << "Hit rate: " << stats.hit_rate << "%\n";
std::cout << "Memory used: " << stats.memory_used / 1_MB << " MB\n";

Preloading Strategy¶

Factory Presets: - Load all factory preset resources on startup - Typically <500MB total - Ensures instant preset loading

User Favorites: - Track most-used presets - Preload their resources - Adaptive based on usage patterns

Recent History: - Keep last 10 presets' resources cached - Quick switching between recent presets

🔍 Similarity Matching¶

Finding Similar Resources¶

When a resource is missing, find similar alternatives:

Matching Criteria: 1. Checksum Match: Exact same file (renamed/moved) 2. Filename Match: Similar name (edit distance) 3. Type Match: Same resource type (sample, wavetable, IR) 4. Size Match: Similar file size (±10%) 5. Acoustic Similarity: Audio feature matching (advanced)

Example:

// Original resource not found: "kick_808_punchy.wav"
auto similar = resource_manager.findSimilarResource(
    resource_ref,
    SimilarityOptions{
        .type_match = true,
        .name_match = true,
        .max_results = 5
    }
);

// Results:
// 1. kick_808.wav (90% match)
// 2. kick_909_punchy.wav (75% match)
// 3. kick_acoustic.wav (60% match)

📊 Resource Database¶

Indexing System¶

Build searchable index of all resources:

ResourceScanner scanner;

// Scan directories
scanner.scanDirectory("C:/AudioLab/Resources");
scanner.scanDirectory("C:/Users/Me/Samples");

// Build database
auto database = scanner.buildDatabase();

// Query
auto results = database.findByType("sample");
auto kick_samples = database.findByName("*kick*");
auto by_checksum = database.findByChecksum("sha256:abc123...");

Database Fields: - Path (absolute) - Checksum (SHA256) - Type (sample, wavetable, IR, LUT) - Size (bytes) - Sample rate (for audio) - Duration (for audio) - Metadata (tags, description)

⚡ Performance Targets¶

Operation	Target	Typical
Cache lookup	<1 μs	0.5 μs
Resource load (cached)	<10 μs	5 μs
Resource load (disk)	<10 ms	5 ms
Resource load (cloud)	<500 ms	200 ms
Checksum verification	<5 ms	2 ms
Similarity search	<50 ms	20 ms
Cache eviction	<1 ms	0.5 ms

🧪 Usage Examples¶

Example 1: Load Resource¶

#include "resource_manager.hpp"

// Get resource ref from preset
auto ref = preset.getResourceRef("kick_sample");

// Load resource
ResourceManager manager;
auto resource = manager.loadResource(ref);

if (resource.isValid()) {
    auto data = resource.getData();
    auto size = resource.getSize();

    // Use resource
    processAudio(data, size);
}

Example 2: Preload Resources¶

ResourceManager manager;

// Preload factory presets
manager.preloadPattern("factory/*");

// Preload user favorites
std::vector<std::string> favorites = getUserFavorites();
manager.preloadResources(favorites);

Example 3: Handle Missing Resource¶

auto resource = manager.loadResource(ref);

if (!resource.isValid()) {
    // Try fallback
    if (ref.has_fallback()) {
        resource = manager.loadResource(ref.getFallback());
    }

    // Still not found? Find similar
    if (!resource.isValid()) {
        auto similar = manager.findSimilarResource(ref);
        if (!similar.empty()) {
            resource = manager.loadResource(similar[0]);
        }
    }

    // Last resort: use default
    if (!resource.isValid()) {
        resource = manager.getDefaultResource(ref.getType());
    }
}

Example 4: Cache Statistics¶

auto& cache = manager.getCache();

// Get statistics
auto stats = cache.getStatistics();

std::cout << "Cache Statistics:\n";
std::cout << "  Entries: " << stats.entry_count << "\n";
std::cout << "  Memory: " << stats.memory_used / 1_MB << " MB\n";
std::cout << "  Hit rate: " << stats.hit_rate << "%\n";
std::cout << "  Evictions: " << stats.eviction_count << "\n";

🔧 Configuration¶

Cache Configuration¶

ResourceCache::Config config;
config.max_memory_bytes = 2_GB;
config.max_entries = 10000;
config.eviction_policy = EvictionPolicy::LRU;
config.preload_factory = true;
config.preload_favorites = true;

ResourceCache cache(config);

Resolver Configuration¶

ResourceResolver::Config config;
config.search_paths = {
    "C:/AudioLab/Resources",
    "C:/Users/Me/Samples",
    "%APPDATA%/AudioLab/Resources"
};
config.enable_cloud = true;
config.cloud_timeout_ms = 5000;
config.verify_checksums = true;
config.enable_similarity = true;

ResourceResolver resolver(config);

📝 Resource Types¶

Supported Types¶

Sample (.wav, .aiff, .flac)
Audio samples
One-shot sounds
Loops
Wavetable (.wav, .wt)
Single-cycle waveforms
Wavetable banks
Typically 2048 samples
Impulse Response (.wav, .ir)
Reverb IRs
Cabinet IRs
Effect IRs
Lookup Table (.lut, .csv)
Waveshaping curves
Transfer functions
Coefficient tables
MIDI File (.mid)
Sequences
Patterns
Arpeggios
Image (.png, .jpg)
Custom UI backgrounds
Visualizations
Logos

🔐 Security¶

Checksum Verification¶

All resources verified with SHA256:

bool ResourceManager::verifyChecksum(
    const std::vector<uint8_t>& data,
    const std::string& expected_checksum) {

    auto calculated = calculateSHA256(data);
    return calculated == expected_checksum;
}

Safe Cloud Downloads¶

// Only download from trusted domains
const std::vector<std::string> TRUSTED_DOMAINS = {
    "cdn.audiolab.com",
    "resources.audiolab.com"
};

bool isTrustedUrl(const std::string& url) {
    for (const auto& domain : TRUSTED_DOMAINS) {
        if (url.find(domain) != std::string::npos) {
            return true;
        }
    }
    return false;
}

Preset Schemas (TAREA 1): ResourceRef definition
Serialization Engine (TAREA 2): Embed resources in presets
Version Management (TAREA 3): Migrate resource references
Cloud Integration (TAREA 10): Download resources from CDN

📊 Metrics & Monitoring¶

Key Metrics¶

Cache hit rate: >90% (factory presets), >70% (user presets)
Average load time: <10ms (cached), <50ms (disk)
Memory usage: <2GB under normal use
Resource availability: >95% (with fallbacks)

Monitoring¶

// Log cache statistics
manager.setStatisticsCallback([](const auto& stats) {
    if (stats.hit_rate < 0.7) {
        LOG_WARNING("Low cache hit rate: " << stats.hit_rate);
    }

    if (stats.memory_used > 1.8_GB) {
        LOG_WARNING("Cache memory usage high: "
                   << stats.memory_used / 1_GB << " GB");
    }
});

Status: 🔄 In Development Last Updated: 2025-01-15 Version: 1.0.0