A modern, high-performance audio analysis service featuring a hybrid Deno-Python architecture for extracting rhythm and melody information from audio files.

• Beat-Quantized Melody Extraction - Advanced 3-phase analysis pipeline
• Real-time Progress Tracking - Server-Sent Events for live updates
• Dual Backend Support - Redis for production, in-memory for development
• Comprehensive API Documentation - OpenAPI/ReDoc integration
• Type-Safe Architecture - Zod validation and TypeScript throughout
• Production Ready - Docker containers with health checks
• Test-Driven Development - Comprehensive test coverage

┌─────────────────┐    IPC     ┌──────────────────┐
│   Deno API      │◄──────────►│  Python Engine   │
│   (TypeScript)  │   JSON     │   (Standalone)   │
└─────────────────┘            └──────────────────┘
        │                              │
        ▼                              ▼
┌─────────────────┐            ┌──────────────────┐
│     Redis       │            │    Librosa       │
│  (Task Queue)   │            │ (Audio Analysis) │
└─────────────────┘            └──────────────────┘

• Deno API Server - High-performance HTTP server with Oak framework
• Python Analysis Engine - Standalone executable for audio processing
• Redis Backend - Task management and result storage (optional)
• Docker Integration - Multi-service containerized deployment

• Deno 1.45+ (installation guide)
• Python 3.9+ with pip
• Docker & Docker Compose (for containerized deployment)
• Make (optional, for simplified commands)

# Clone and setup
git clone <repository-url>
cd TypoSync

# Setup development environment
make setup

# Start development server (choose one)
make dev          # Docker with in-memory backend
make dev-redis    # Docker with Redis backend  
make dev-local    # Local development (no Docker)

# Setup Deno API
cd api
deno cache deps.ts

# Setup Python engine
cd ../rhythm_engine
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

# Start development
cd ../api
deno task dev

# Development with hot reload
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up --build

# Production deployment
docker-compose up --build

curl -X POST "http://localhost:8000/analyze" \
  -F "[email protected]" \
  -H "Content-Type: multipart/form-data"

Response:

{
  "task_id": "01HF7XQZX8R3VTFN95QG9MJZT0",
  "backend": "in-memory"
}

const eventSource = new EventSource('http://localhost:8000/stream/01HF7XQZX8R3VTFN95QG9MJZT0');

eventSource.onmessage = function(event) {
  const data = JSON.parse(event.data);
  console.log('Status:', data.state);
  
  if (data.state === 'SUCCESS') {
    console.log('BPM:', data.result.bpm);
    console.log('Melody:', data.result.melody_map);
    eventSource.close();
  }
};

curl "http://localhost:8000/results/01HF7XQZX8R3VTFN95QG9MJZT0"

• Interactive Docs: http://localhost:8000/docs
• OpenAPI Spec: http://localhost:8000/docs/openapi.yaml
• Health Check: http://localhost:8000/

make test                    # All tests
make test-coverage          # With coverage reports

# Deno API tests
cd api && deno task test

# Python engine tests  
cd rhythm_engine && python test_run.py

# Integration tests
cd api && deno test --allow-all tests/integration_test.ts

# Watch mode for TDD
cd api && deno task dev     # Auto-restart on changes
cd api && deno task test    # Run tests on changes

Create .env file (copy from .env.example):

# API Configuration
PORT=8000
LOG_LEVEL=INFO

# Backend Selection
REDIS_URL=redis://localhost:6379/0  # Enable Redis (comment out for in-memory)

# Python Engine
PYTHON_EXECUTABLE=python3
MIN_NOTE_DURATION=0.05

# File Uploads
MAX_FILE_SIZE=52428800  # 50MB
UPLOAD_DIR=./uploads

• In-Memory (Development): Fast, no persistence
• Redis (Production): Scalable, persistent, distributed

# Docker with in-memory backend (fastest setup)
make dev

# Docker with Redis backend (production-like)
make dev-redis

# Local development (no Docker, fastest iteration)
make dev-local

# Full production stack
make prod

# With reverse proxy
docker-compose --profile production up

make docker-build          # Build images
make docker-test           # Test deployment
make clean                 # Cleanup containers

The audio analysis follows a sophisticated 3-phase approach:

• Beat Tracking: Establish rhythm grid using librosa
• Pitch Detection: Extract fundamental frequencies with PYIN algorithm

• Grid Creation: 8th note subdivisions within beat boundaries
• Dominant Notes: Most common pitch per subdivision

• Note Merging: Combine consecutive identical pitches
• Duration Filter: Remove notes below minimum threshold (default: 0.05s)

{
  "bpm": 120.0,
  "beat_timestamps": [0.0, 0.5, 1.0, 1.5],
  "melody_map": [
    {
      "pitch": "A4",
      "start_time": 1.23,
      "duration": 0.45
    }
  ],
  "analysis_info": {
    "total_beats": 150,
    "total_subdivisions": 300,
    "consolidated_notes": 100,
    "filtered_notes": 80,
    "min_note_duration": 0.05,
    "subdivision_factor": 2
  }
}

TypoSync/
├── api/                    # Deno TypeScript API
│   ├── controllers/        # Request handlers
│   ├── services/          # Business logic
│   ├── types/             # Schemas and types
│   ├── middleware/        # Custom middleware
│   ├── tests/             # Test suites
│   └── main.ts           # Application entry
├── rhythm_engine/         # Python analysis engine
│   ├── app/              # FastAPI legacy code
│   ├── run.py            # Standalone executable
│   └── test_run.py       # Engine tests
├── docker-compose.yml    # Production containers
├── Makefile             # Development commands
└── CLAUDE.md           # AI assistant guidance

1. Write Tests First (TDD approach)
2. Update Schemas in api/types/schemas.ts
3. Implement Logic in appropriate service/controller
4. Update OpenAPI documentation
5. Test Integration with Docker

make format              # Format code
make lint               # Lint code
make health             # Check services

• Deno Runtime: V8 engine with TypeScript optimization
• Python Engine: Isolated processes for audio analysis
• Redis Clustering: Scale task management horizontally
• Load Balancing: Nginx reverse proxy configuration

• Health Checks: Container and service monitoring
• Structured Logging: JSON logs for analysis
• Metrics: Task completion rates and processing times

• Non-root Containers: Security-hardened images
• File Validation: MIME type and size checking
• Input Sanitization: Filename and path validation
• Resource Limits: Container resource constraints

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Write tests for your changes
4. Implement the feature
5. Test thoroughly: make test
6. Commit changes: git commit -m 'Add amazing feature'
7. Push to branch: git push origin feature/amazing-feature
8. Open Pull Request

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

• Documentation: http://localhost:8000/docs
• Issues: GitHub Issues
• Discussions: GitHub Discussions

• Librosa - Python audio analysis library
• Deno - Modern JavaScript/TypeScript runtime
• Oak - Web framework for Deno
• Redis - In-memory data structure store