Skip to content

FIRST_TIME_SETUP.md

Latest commit

 

History

History
280 lines (210 loc) · 7.39 KB

FIRST_TIME_SETUP.md

File metadata and controls

280 lines (210 loc) · 7.39 KB
Raw

First-Time Setup Guide for Auralis Development

This guide walks you through everything you need to get Auralis running on your machine for the first time.

⏱️ Estimated Time: 20-30 minutes

📋 Prerequisites Checklist

Before you begin, ensure your system has:

  • uv - Manages the Python interpreter + virtual environment (replaces pyenv/venv/pip). Check with uv --version
  • Node.js 24+ LTS - Check with node --version
  • Git - Check with git --version
  • pnpm - Check with pnpm --version (the ONLY supported package manager, #4357; install with corepack enable)
  • Audio libraries (platform-dependent, see section below)
  • ~5GB free disk space for dependencies, database, and build artifacts

🔧 System-Specific Audio Dependencies

Auralis requires audio processing libraries. Install based on your OS:

Linux (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install -y libsndfile1 libsndfile1-dev ffmpeg libavformat-dev libavcodec-dev
# Optional: for better audio backend support
sudo apt-get install -y libflac-dev libogg-dev libvorbis-dev libopus-dev

Linux (Fedora/RHEL)

sudo dnf install -y libsndfile libsndfile-devel ffmpeg

macOS

# Using Homebrew
brew install libsndfile ffmpeg

Windows

Download from:

🚀 Step-by-Step Setup

1️⃣ Clone the Repository

git clone https://github.com/matiaszanolli/Auralis.git
cd Auralis

2️⃣ Set Up Python Environment

# uv creates the venv using the interpreter pinned in .python-version (3.14),
# downloading a uv-managed CPython if you do not already have one.
uv venv
source .venv/bin/activate

Verify activation:

which python  # Should show a path inside .venv
python --version

3️⃣ Install Python Dependencies

uv pip install -r requirements.txt

Expected output: 40-60 packages installed, no errors

4️⃣ Database Initialization

The database initializes automatically on first launch — no manual step required. It creates ~/.auralis/library.db and ~/.auralis/ on startup. To reset, delete the file: rm ~/.auralis/library.db

5️⃣ Set Up Node.js & Frontend Dependencies

# Check Node version
node --version  # Should be 24+ LTS

# Install frontend dependencies
cd auralis-web/frontend
pnpm install
cd ../..

Expected output: ~1000+ packages installed

6️⃣ Verify Environment Configuration

The project uses environment variables from .env:

cat .env

For local development, these defaults should work:

  • Backend runs on http://localhost:8765
  • Frontend dev server runs on http://localhost:3000
  • Database uses SQLite at ~/.auralis/library.db

To override for your setup:

cp .env .env.local  # Create local override (not tracked by git)
# Edit .env.local as needed

✅ Verify Your Setup

Quick Verification Script

echo "=== Python ==="
python --version
python -c "import numpy, scipy, fastapi, pytest; print('✅ Core Python packages OK')"

echo "=== Node ==="
node --version
pnpm --version

echo "=== Database ==="
ls -lh ~/.auralis/library.db

echo "=== Audio Libraries ==="
python -c "import soundfile; print('✅ Audio I/O OK')"

echo "=== Frontend ==="
cd auralis-web/frontend && pnpm list react react-dom 2>/dev/null | head -5

🎯 Run Your First Development Session

Option A: Full Web Interface (Recommended)

# From project root
python launch-auralis-web.py --dev

Then visit:

Option B: Backend Only

cd auralis-web/backend
python -m uvicorn main:app --reload
# Visit http://localhost:8765/api/docs

Option C: Frontend Only

cd auralis-web/frontend
pnpm run dev
# Visit http://localhost:3000

🧪 Run Tests to Verify Everything Works

Backend Tests (Fast, skips slow tests)

python -m pytest tests/ -m "not slow" -v --tb=short
# Expected: 700+ tests passing in ~1-2 minutes

Frontend Tests (Watch mode)

cd auralis-web/frontend
pnpm test
# Press 'q' to quit, 'a' to run all tests

📚 Next Steps

  1. Read the main architecture guide: CLAUDE.md - Overall architecture and patterns
  2. Understand the audio pipeline: ADAPTIVE_MASTERING_SYSTEM.md
  3. Learn the testing approach: docs/development/TESTING_GUIDELINES.md
  4. Explore the codebase: Start with auralis/core/hybrid_processor.py (main audio pipeline)

🛠️ IDE Setup (Optional but Recommended)

VS Code

  1. Install extensions:

    • Python (Microsoft)
    • Pylance (Microsoft)
    • Black Formatter (Microsoft)
    • TypeScript Vue Plugin (Vue)
    • ESLint (Microsoft)
    • Prettier (Code Formatter)

  2. Settings (.vscode/settings.json - already partially configured):

    {
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.linting.enabled": true,
  "python.formatting.provider": "black",
  "editor.formatOnSave": true
}

  3. Debug Python:

    • Press Ctrl+Shift+D (or Cmd+Shift+D on macOS)
    • Click "Run and Debug"
    • Select "Python" from dropdown

⚠️ Common First-Time Issues & Fixes

Issue Solution
python: command not found Run uv venv && source .venv/bin/activate, or use python3 instead
ModuleNotFoundError: numpy Did you activate the venv? source .venv/bin/activate, then uv pip install -r requirements.txt
libsndfile not found Install audio libraries (see section above)
Port 8765 already in use Kill existing process: lsof -ti:8765 | xargs kill -9
SQLite database locked Delete database: rm ~/.auralis/library.db (will rescan)
pnpm: command not found Install Node 24+ LTS from https://nodejs.org/, then corepack enable
Module not found (TypeScript) Run cd auralis-web/frontend && pnpm install
Audio file won't play Install ffmpeg: brew install ffmpeg (macOS) or apt-get (Linux)

🔍 Verify Audio Backend

The system uses audioread which supports multiple backends. Check which backends are available:

python -c "
import audioread
print('Available audioread backends:')
for backend in audioread.get_backends():
    print(f'  ✅ {backend.__name__}')
"

Expected output (at least one):

  • FFmpeg (most flexible)
  • libsndfile
  • core audio (macOS)
  • WinMM (Windows)

📞 Need Help?

  • Setup issues: Check "Common First-Time Issues" section above
  • Audio problems: See AUDIO_DEPENDENCY_TROUBLESHOOTING.md (reference in CLAUDE.md)
  • Architecture questions: Read CLAUDE.md
  • Bug reports: Create a GitHub issue with setup details

🎉 You're Ready!

Once setup completes successfully, you should:

Happy developing! 🎵