Sfx Catalog

1. Not searchable - Generic filenames, no metadata
2. Not reusable - Can't remember which sounds work for which scenes
3. Not learnable - No pattern recognition across projects

Solution: The sfx-catalog system makes sound effects discoverable, reusable, and learnable.

Core Features

1. Audio Analysis

Extracts technical characteristics from MP3 files:

• Duration, frequency profile, envelope (ADSR)
• Loudness metrics, harmonic content
• Automatic categorization (impact, ambient, foley, etc.)

2. Semantic Search

Natural language queries powered by memory integration:

./run.sh search "deep ominous thunder"
# Returns ranked results with similarity scores

3. Memory First

Learns from prior usage to improve recommendations:

./run.sh recall-usage "tense apartment entrance"
# Returns SFX successfully used in similar scenes before

4. Usage Tracking

Records context for every SFX selection:

./run.sh record-usage \
    --sfx-id abc123 \
    --project "Dark Horizon" \
    --scene "INT. APARTMENT - Sarah enters cautiously" \
    --rationale "Adds tension to entrance"

5. On-Demand Generation

Creates missing sound effects via AI when library lacks options:

./run.sh generate "metallic door slam" --duration 2.5 --ingest

Integration Points

create-movie

Automatically selects and applies SFX during movie generation:

# In create-movie workflow
from sfx_catalog.query_engine import SFXQueryEngine

engine = SFXQueryEngine(scope="horus_lore")

# Memory First: Check for prior usage
sfx = engine.recall_usage(scene_description)

# Fallback: Semantic search
if not sfx:
    sfx = engine.search(query, categories, duration_range)

# Record for future learning
engine.record_usage(sfx_id, project, scene, timestamp, rationale)

create-storyboard

Suggests sound effects during storyboard planning:

# During storyboard phase
suggestions = suggest_sfx_for_shot(shot)
# Returns natural language recommendations with alternatives

Architecture

High-level system design:

┌─────────────────┐
│ 166 MP3 Files   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ┌──────────────────┐
│ Audio Analyzer  │────►│ Content Class.   │
│ (librosa)       │     │ (rule-based)     │
└─────────────────┘     └────────┬─────────┘
                                 │
                                 ▼
                        ┌──────────────────┐
                        │ Metadata Gen.    │
                        │ (LLM-assisted)   │
                        └────────┬─────────┘
                                 │
                                 ▼
                        ┌──────────────────┐
                        │ JSON Manifest    │
                        └────────┬─────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────┐
│          ArangoDB Memory                │
│  ┌────────────┐  ┌────────────────┐    │
│  │sfx_library │  │  sfx_usage     │    │
│  │(catalog)   │  │  (tracking)    │    │
│  └────────────┘  └────────────────┘    │
│  ┌────────────┐                         │
│  │sfx_generated                         │
│  │(cache)     │                         │
│  └────────────┘                         │
└─────────────────────────────────────────┘
         │
         ▼
┌─────────────────┐
│ Query Engine    │ ◄──── create-movie, create-storyboard
│ (multi-strategy)│
└─────────────────┘

Deep Dive: See ARCHITECTURE.md for detailed component specifications.

Memory Schema

SFX data is stored in ArangoDB with three main collections:

sfx_library - Sound Effect Catalog

{
  "_key": "sfx_abc123",
  "file_path": "/mnt/storage12tb/media/sfx/...",
  "description": "Deep, punchy impact with quick attack",
  "categories": ["impact", "low_frequency"],
  "audio_features": {
    "duration_seconds": 2.34,
    "envelope": {...},
    "frequency_profile": {...}
  },
  "embedding": [...],
  "usage_count": 5
}

sfx_usage - Usage History

{
  "sfx_id": "sfx_library/sfx_abc123",
  "project_name": "Dark Horizon",
  "scene_description": "INT. APARTMENT - Tense entrance",
  "timestamp_in_scene": 2.5,
  "rationale": "Adds atmosphere and tension"
}

sfx_generated - Generation Cache

{
  "prompt": "metallic door creak",
  "file_path": "/mnt/.../generated/door_creak.mp3",
  "reuse_count": 3,
  "user_approved": true
}

Deep Dive: See MEMORY_SCHEMA.md for complete schema, indices, and query patterns.

CLI Commands

Core Workflow

# 1. Catalog audio files
./run.sh catalog <directory> --output manifest.json

# 2. Ingest into memory
./run.sh ingest manifest.json

# 3. Search catalog
./run.sh search "explosion boom" --categories impact --duration 2-5

# 4. Check system status
./run.sh status

Advanced Operations

# Record usage after selection
./run.sh record-usage \
    --sfx-id abc123 \
    --project "Dark Horizon" \
    --scene "INT. WAREHOUSE - Explosion" \
    --timestamp 5.2

# Recall prior usage (Memory First)
./run.sh recall-usage "warehouse explosion scene"

# Find similar sounds
./run.sh similar sfx_abc123 --threshold 0.80

# Generate missing SFX
./run.sh generate "deep rumbling thunder" --duration 4.0 --ingest

# View usage statistics
./run.sh stats --type categories

Full Reference: See API.md for complete command documentation and Python API.

Python API

For programmatic integration:

from sfx_catalog import SFXQueryEngine

engine = SFXQueryEngine(scope="horus_lore")

# Memory First pattern
prior_usage = engine.recall_usage(
    scene_description="tense entrance scene",
    threshold=0.7
)

# Semantic search with filters
results = engine.search(
    query="door creak",
    categories=["foley"],
    duration_range=(1.0, 3.0),
    k=5
)

# Record usage for learning
engine.record_usage(
    sfx_id="sfx_abc123",
    project_name="Dark Horizon",
    scene_description="INT. APARTMENT - Sarah enters",
    timestamp_in_scene=2.5,
    rationale="Perfect tension builder"
)

# Generate if needed
generated = engine.generate_sfx(
    prompt="metallic door slam",
    duration=2.0,
    check_cache=True,  # Avoid duplicate generation
    ingest=True        # Add to catalog
)

See EXAMPLES.md for detailed usage examples including cataloging, scene matching, usage recording, and SFX generation.

See ARCHITECTURE.md for data flow diagrams, technology stack, performance benchmarks, storage requirements, and configuration.