Audio Analysis Service (@mixtapelabs/audio-analysis-service)

Express microservice that computes lightweight DSP metrics (loudness, crest factor, basic spectral/stereo heuristics) via ffmpeg filters and exposes them through a single authenticated endpoint.

Features

• POST /analysis protected by x-api-key
• GET /health probe
• FfmpegAudioAnalysisService uses ebur128 + astats filters to extract LUFS, loudness range, true peak, crest factor, spectrum balance, and stereo width hints
• Zod validation, ESLint/Prettier, Vitest coverage for service + router layers

Project Structure

src/
 ├─ app.ts                     # Express composition
 ├─ config/env.ts              # zod-validated env loader
 ├─ index.ts                   # bootstrap entrypoint
 ├─ middleware/api-key-auth.ts # reusable middleware
 ├─ routes/analysis.ts         # POST /analysis
 ├─ services/audio-analysis-service.ts
 └─ types/analysis.ts          # shared analysis schema

Requirements

• Node.js ≥ 18
• ffmpeg available. Defaults to ffmpeg-static, but you can override via FFMPEG_PATH
• The service reads audio files directly from disk (path in request body)

Setup

npm install
npm run dev

Scripts: build, start, typecheck, lint, format, test, and generate:api-key.

API Keys

npm run generate:api-key                 # rotate AUDIO_ANALYSIS_API_KEY locally
cd ../api && npm run analysis:api-key    # copy the key into api/.env

Environment Variables

Variable	Description
PORT	HTTP port (default 4002)
AUDIO_ANALYSIS_API_KEY	Shared secret for x-api-key auth
FFMPEG_PATH	Optional override for the ffmpeg binary

.env / .env.example carry the defaults.

HTTP API

curl -X POST http://localhost:4002/analysis \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: super-secret-analysis-key' \
  -d '{"path":"/tmp/test.wav"}'

Response:

{
  "loudness": {
    "integratedLUFS": -14.3,
    "truePeak": -0.8,
    "loudnessRange": 4.1
  },
  "dynamics": { "crestFactor": 13.5 },
  "spectrum": { "low": 0.3, "mids": 0.4, "highs": 0.3 },
  "stereo": { "widthScore": 0.55 }
}

Error Responses

Status	Body	Reason
400	{ "error": "Invalid request body" }	Missing/empty path
401	{ "error": "Unauthorized" }	Missing or invalid x-api-key
500	{ "error": "Failed to analyze audio" }	ffmpeg errors or parsing failures

Docker Build

A Dockerfile is provided for production deployment:

# Build the image
docker build -t audio-analysis-service .

# Run the container
docker run -p 4002:8080 \
  -e PORT=8080 \
  -e AUDIO_ANALYSIS_API_KEY=your-secret-key \
  audio-analysis-service

The Dockerfile:

• Uses node:22-slim base image
• Builds TypeScript from source
• Removes dev dependencies for smaller image
• Exposes port 8080

::: tip Bundled Binary The service uses ffmpeg-static which includes the FFmpeg binary. No system FFmpeg installation required! :::

Railway Deployment

For standalone repo deployment:

Railway will automatically detect the Dockerfile and build with FFmpeg included.

1. Create new Railway project from this repo
2. Railway detects Dockerfile automatically
3. Set environment variable: AUDIO_ANALYSIS_API_KEY
4. Railway builds and deploys

Service URL: Railway provides an internal URL like audio-analysis-service.railway.internal

Use this internal URL in your API service's ANALYSIS_SERVICE_URL environment variable.

Contributing

See CODE OF CONDUCT, CONTRIBUTING, and SECURITY. Submit PRs with npm run lint, npm run typecheck, and npm test passing.