LangGraph-powered workflow engine for AI-driven audio mix analysis.

Mixtape Engine coordinates the analysis pipeline that ingests an uploaded mix, enriches it with metadata, runs deeper signal analysis, and routes results through LLM-backed feedback modules. It aligns toolchains, state, and prompts so downstream services can surface actionable mix insights quickly and consistently.

• Pure TypeScript Node.js library that can be embedded anywhere—CLI tools, API servers, or workers.
• Built on LangGraph to orchestrate the session state machine (validate input → gather metadata → run audio analysis → synthesize LLM feedback).
• Exposes a primary entry point such as runMixtapeSession(input, deps) that drives the workflow while allowing hosts to inject their own clients and storage adapters.

npm install @mixtapelabs/engine --registry=https://npm.pkg.github.com

This package is private. Authenticate with GitHub Packages (or your configured private registry) before installing.

Add the scope/registry mapping to your global or project .npmrc so future installs do not need the --registry flag:

@mixtapelabs:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

import { runMixtapeSession, type MixtapeEngineDeps } from "@mixtapelabs/engine";

const deps: MixtapeEngineDeps = {
  audioMetadataClient: {
    async getMetadata({ url }) {
      // Call your storage/ffprobe service
      return {
        durationSec: 210,
        format: "wav",
        sampleRate: 48000,
        channels: 2,
        bitrate: 320000,
      };
    },
  },
  audioAnalysisClient: {
    async analyze({ url }) {
      // Call your DSP service
      return {
        loudness: { integratedLUFS: -10.5, truePeak: -0.9, loudnessRange: 6.3 },
        dynamics: { crestFactor: 9 },
        spectrum: { low: -12, mids: -8, highs: -7 },
        stereo: { widthScore: 0.72 },
      };
    },
  },
  feedbackClient: {
    async generateFeedback(state) {
      return {
        feedbackText: `Dummy feedback for ${state.sessionId}`,
        suggestions: ["Tighten low mids", "Relax bus compression", "Open up highs"],
      };
    },
  },
};

const result = await runMixtapeSession(
  {
    sessionId: "mix_123",
    uploadUrl: "https://uploads.mixtapelabs.com/mix.wav",
    userContext: {
      daw: "Ableton Live",
      genre: "house",
      experienceLevel: "intermediate",
    },
  },
  deps,
);

Provide dependency clients that already know how to talk to your storage, DSP, and LLM infrastructure. The engine orchestrates state internally and returns structured insights or populates error when a node fails.

If you want the built-in OpenAIFeedbackClient, set OPENAI_API_KEY in the host environment and construct the client before passing it into the deps object.

import { OpenAIFeedbackClient } from "@mixtapelabs/engine";

const deps = {
  audioMetadataClient,
  audioAnalysisClient,
  feedbackClient: new OpenAIFeedbackClient({ model: "gpt-4o-mini" }),
};

Set engine-wide configuration through environment variables consumed by your injected clients. Common variables include:

• OPENAI_API_KEY – required when using OpenAIFeedbackClient.
• MIXTAPELABS_ENV – optional flag for logging/observability differences.
• Any downstream secrets (storage tokens, DSP endpoints) used by your custom clients.

Never commit secrets to this repository. Prefer host-level configuration injection.

npm install
npm run lint
npm run typecheck
npm test
npm run build
npm run ci      # one-shot lint + typecheck + test + build
npm run docs:dev   # VitePress docs dev server
npm run docs:build # Build static docs

test/ contains both unit and integration coverage (LangGraph nodes, state schemas, prompt builder, and the public runMixtapeSession flow). The CI workflow runs the same commands and must be green before merging or tagging.

Artifacts live under dist/ (ESM + CJS + type definitions) and only that directory plus README.md/LICENSE is shipped thanks to the "files" whitelist. To cut a release:

npm ci
npm run lint
npm run typecheck
npm test
npm run build
npm publish --access public   # or npm publish --registry <private>

The prepare script runs npm run build, so npm publish automatically bundles the latest sources. See docs/releasing.md for registry auth details.

CI Release workflow: add a GH_TOKEN secret (with read:packages, write:packages, repo) so .github/workflows/release.yml can authenticate to GitHub Packages during automated publishes. Falls back to GITHUB_TOKEN if GH_TOKEN is not set, but the dedicated token is recommended.

• Docs live in the /docs directory and are powered by VitePress.
• npm run docs:dev launches a local site at http://localhost:5173.
• .github/workflows/docs.yml builds the site on pushes to main and force-pushes it to a companion repository (defaults to mixtapelabs/engine-docs on the gh-pages branch). Configure the DOCS_PUBLISH_TOKEN secret plus optional DOCS_REPOSITORY/DOCS_BRANCH action variables to control the destination.
• Key sections cover onboarding, session state schemas, dependency injection, LangGraph behavior, prompting, testing, AI collaboration, and release practices.

The engine expects its host to supply any sensitive configuration such as OPENAI_API_KEY, vector-store URLs, or analytics tokens. Do not hardcode secrets in code; inject them through your dependency clients.

Proprietary. All rights reserved. See LICENSE for details.