Audio Feedback Service (@mixtapelabs/audio-feedback-service)

Express microservice that turns the engine’s fileInfo, analysis, and userContext payloads into actionable mix guidance using OpenAI’s Responses API. It shares the same tooling and auth patterns as the other services.

Features

• POST /feedback endpoint protected by x-api-key
• Health endpoint (GET /health)
• Zod validation + typed service interface
• Vitest coverage for service + router layers
• ESLint/Prettier/TypeScript toolchain aligned with the rest of the repo

Project Structure

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

Requirements

• Node.js ≥ 18
• OpenAI API access (OPENAI_API_KEY)
• The API/engine must send the analysis payload; this service does not re-fetch metadata/analysis itself

Setup

npm install
npm run dev

Scripts mirror the other services: dev, build, start, typecheck, lint, format, test, and generate:api-key.

API Keys

npm run generate:api-key                 # update AUDIO_FEEDBACK_API_KEY locally
cd ../api && npm run metadata:api-key    # reuse sync script patterns if desired

Environment Variables

Variable	Description
PORT	HTTP port (default 4003)
AUDIO_FEEDBACK_API_KEY	Shared secret used for x-api-key auth
OPENAI_API_KEY	Token used by the OpenAI client
OPENAI_MODEL	Model ID (defaults to gpt-4.1-mini)
OPENAI_BASE_URL	Optional custom base URL/proxy

.env and .env.example contain the defaults.

HTTP API

curl -X POST http://localhost:4003/feedback \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: super-secret-feedback-key' \
  -d '{
        "fileInfo": { "durationSec": 210, "format": "wav", "sampleRate": 48000, "channels": 2 },
        "analysis": { "loudness": { "integratedLUFS": -9.5, "truePeak": -0.7, "loudnessRange": 6 } },
        "userContext": { "genre": "house", "experienceLevel": "intermediate" }
      }'

Response:

{
  "feedbackText": "Overall your mix is punchy but could breathe more in the chorus...",
  "suggestions": [
    "Lower overall loudness by ~1 dB to avoid clips on streaming platforms.",
    "Tighten low-mids around 300 Hz to make space for vocals.",
    "Automate stereo widening so the chorus feels wider than the verse."
  ]
}

Contributing

See CODE OF CONDUCT, CONTRIBUTING, and SECURITY docs. Pull requests should pass npm run lint, npm run typecheck, and npm test.