AniMUL Server

Web application for analyzing audio files using AI. Powered by the AniMUL model, a fine-tune of Qwen3-Omni trained on the Earth Species Project's NatureLM-audio-training dataset.

🌐 Live Application: https://animul.ai

📦 Source Code: https://spacecruft.org/deepcrayon/AniMUL-server

🎯 Features

• Audio Analysis: Upload audio files and receive detailed AI-generated descriptions
• Nature Sound Recognition: Specialized in identifying and describing nature sounds
• Streaming Responses: Real-time analysis display as results are generated
• Multiple Formats: Support for WAV, MP3, FLAC, OGG, M4A, WebM, AAC
• Modern UI: Responsive dark-themed interface with drag-and-drop upload

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     User's Browser                               │
│                   (Svelte 5 Frontend)                            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              Web Server (Apache + FastAPI)                       │
│  • Static file serving (Svelte build)                           │
│  • REST API for audio analysis                                  │
│  • Streaming responses (SSE)                                    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              vLLM Server                                         │
│  • AniMUL model (fine-tuned from Qwen3-Omni)                    │
│  • OpenAI-compatible API                                        │
└─────────────────────────────────────────────────────────────────┘

🚀 Quick Start

Prerequisites

• Python 3.11+
• Node.js 20+
• Access to a vLLM server with the AniMUL model

Development Setup

# Clone the repository
git clone https://spacecruft.org/deepcrayon/AniMUL-server.git
cd AniMUL-server

# Backend setup
cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp src/server/.env.example src/server/.env
# Edit .env with your vLLM server settings

# Frontend setup
cd ../frontend
npm install

# Start development servers
# Terminal 1: Backend
cd backend && source .venv/bin/activate && uvicorn server.main:app --reload

# Terminal 2: Frontend
cd frontend && npm run dev

Visit http://localhost:5173 to use the application.

📁 Project Structure

AniMUL-server/
├── backend/                 # FastAPI backend
│   ├── src/server/
│   │   ├── api/            # API routes and schemas
│   │   ├── services/       # vLLM client
│   │   ├── utils/          # Audio utilities
│   │   └── tests/          # Unit tests
│   └── pyproject.toml
├── frontend/               # Svelte 5 frontend
│   ├── src/
│   │   ├── lib/           # Components and API client
│   │   └── routes/        # SvelteKit pages
│   └── package.json
├── docs/                   # Documentation
│   ├── QUICKSTART.md      # Development setup guide
│   ├── DEPLOYMENT.md      # Production deployment guide
│   └── PLAN.md            # Architecture and planning
└── scripts/               # Deployment scripts
    ├── deploy-production.sh
    ├── apache/            # Apache configuration
    └── systemd/           # Systemd service files

📖 Documentation

• Quick Start Guide - Development environment setup
• Deployment Guide - Production deployment instructions
• Development Plan - Architecture and implementation details
• Backend README - API documentation
• Frontend README - Component documentation

🔧 Technology Stack

Component	Technology	Version
Frontend	Svelte 5 + SvelteKit	^5.0.0
Backend	FastAPI	^0.124.0
Python	Python	^3.11
Model Server	vLLM	Latest
Web Server	Apache	2.4.x

🤖 About the AniMUL Model

AniMUL is a fine-tuned version of Qwen3-Omni, specifically trained on the Earth Species Project's NatureLM-audio-training dataset. This specialized training enables the model to:

• Accurately identify and describe nature sounds (birdsong, animal calls, environmental sounds)
• Provide detailed acoustic descriptions
• Recognize species-specific vocalizations
• Describe complex soundscapes with multiple audio sources

Model: deepcrayon/AniMUL-v1

🌐 API Endpoints

Endpoint	Method	Description
/api/health	GET	Health check
/api/analyze	POST	Analyze audio file
/api/analyze/stream	POST	Analyze with streaming response
/api/models	GET	List available models
/api/formats	GET	List supported audio formats

🧪 Testing

# Backend tests
cd backend
pytest --cov

# Frontend type checking
cd frontend
npm run check

🚢 Deployment

For production deployment on Debian with Apache:

# Run deployment script
./scripts/deploy-production.sh

See DEPLOYMENT.md for detailed instructions.

🙏 Acknowledgments

• Earth Species Project for the NatureLM-audio-training dataset
• Qwen Team for the Qwen3-Omni base model
• vLLM for the inference server

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Copyright © 2025, 2026 Jeff Moe