Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

17.6 KB
Raw Blame
/**
 * Rounds API
 *
 *   GET    /api/rounds        → { rounds }
 *   GET    /api/rounds/:id    → { round }
 *   POST   /api/rounds        → { round }   (body: roundInputSchema)
 *   PATCH  /api/rounds/:id    → { round }   (body: roundInputSchema.partial())
 *   DELETE /api/rounds/:id    → { id }
 *
 * The a cappella round workbench: write/arrange rounds and track which voice
 * layers you're learning. Bounds come from services/rounds.js so the Zod schema
 * here and the service-layer sanitizer agree by construction (the dashboard-
 * layouts pattern).
 */

import { Router } from 'express';
import { z } from 'zod';
import { asyncHandler, ServerError } from '../lib/errorHandler.js';
import { validateRequest } from '../lib/validation.js';
import * as svc from '../services/rounds.js';
import { generateRound, evaluateRound, deriveRoundParts } from '../services/roundsAI.js';
import {
  startReferenceAudioImport,
  attachReferenceAudioSseClient,
  cancelReferenceAudioImport,
} from '../services/roundReferenceAudioImport.js';
import {
  startMidiTranscription,
  attachMidiTranscriptionSseClient,
  cancelMidiTranscription,
  MUSCRIPTOR_MODELS,
} from '../services/audioMidiTranscription.js';
import { PATHS } from '../lib/fileUtils.js';
import { safeUnder } from '../lib/ffmpeg.js';

const router = Router();

// Trim then cap, allowing empty (the client clears a field by sending '').
const str = (max) => z.string().trim().max(max);

const sectionSchema = z.object({
  id: str(svc.ID_MAX_LENGTH).optional(),
  label: str(svc.LABEL_MAX_LENGTH).optional().default(''),
  lyrics: str(svc.FIELD_MAX_LENGTH).optional().default(''),
});

const layerSchema = z.object({
  id: str(svc.ID_MAX_LENGTH).optional(),
  label: str(svc.LABEL_MAX_LENGTH).optional().default(''),
  part: str(svc.PART_MAX_LENGTH).optional().default(''),
  notes: str(svc.FIELD_MAX_LENGTH).optional().default(''),
});

// One downsampled tuner sample from a take's pitch trace (#1027). hz/cents/
// clarity are nullable so a silent frame round-trips; the service clamps tMs.
const pitchSampleSchema = z.object({
  tMs: z.number().optional(),
  hz: z.number().nullable().optional(),
  cents: z.number().nullable().optional(),
  clarity: z.number().nullable().optional(),
});

// Per-take color-match accuracy summary (#1027), mirroring colorMatch's
// summarizeAccuracy output. All fields optional/absent-tolerant; the service
// clamps the percentage and drops unrecognized grades.
const accuracySchema = z.object({
  percentInTune: z.number().optional(),
  graded: z.number().optional(),
  counts: z.object({
    'in-tune': z.number().optional(),
    close: z.number().optional(),
    off: z.number().optional(),
    missed: z.number().optional(),
  }).optional(),
  perNote: z.array(z.string()).max(svc.PER_NOTE_GRADES_MAX).optional(),
});

// A saved vocal take. `filename` is the /api/uploads file the audio is served
// from (the client uploads the WAV first, then PATCHes the round with the returned
// filename). Numbers are accepted for the mixer; the service clamps them.
// `pitchTrack`/`accuracy` are optional per-take pitch analysis (#1027) — absent
// on legacy/unscored takes, persisted so the tuner history isn't recomputed.
const recordingSchema = z.object({
  id: str(svc.ID_MAX_LENGTH).optional(),
  layerId: str(svc.ID_MAX_LENGTH).optional().default(''),
  label: str(svc.LABEL_MAX_LENGTH).optional().default(''),
  filename: str(svc.URL_MAX_LENGTH),
  durationMs: z.number().nonnegative().optional(),
  peak: z.number().min(0).max(1).optional(),
  muted: z.boolean().optional(),
  createdAt: z.string().optional(),
  pitchTrack: z.array(pitchSampleSchema).max(svc.PITCH_TRACK_MAX).optional(),
  accuracy: accuracySchema.optional(),
});

// One training attempt — a graded take of one scope (#1028). The service clamps
// the percent and drops zero-note attempts; the schema only types the fields.
const attemptSchema = z.object({
  percentInTune: z.number().optional(),
  graded: z.number().optional(),
  at: z.string().optional(),
});

// Training progress (#1028): `{ history: { <scope>: [attempt…] } }`. A record
// of the scope → recent graded attempts; the service bounds both the per-scope
// history and the number of scopes, and recomputes derived stats client-side.
// `.passthrough()` is NOT used — only `history` is meaningful, and the service
// re-sanitizes regardless, but typing it keeps the contract explicit.
const progressSchema = z.object({
  history: z.record(z.string(), z.array(attemptSchema).max(svc.PROGRESS_HISTORY_MAX)).optional(),
}).optional();

// A sheet-music part — a harmony variation of the base score, in the same
// lead-sheet DSL. `score` is required (a part without notation is meaningless);
// `role` is a HARMONY_PARTS id when known but free-text-safe.
const scorePartSchema = z.object({
  id: str(svc.ID_MAX_LENGTH).optional(),
  label: str(svc.LABEL_MAX_LENGTH).optional().default(''),
  role: str(svc.ID_MAX_LENGTH).optional().default(''),
  score: str(svc.SCORE_MAX_LENGTH),
});

// One labeled time range on a reference's attached audio (#2106). The service
// clamps times and drops zero/negative-length spans; the schema only types the
// fields (startMs/endMs required — a span without both selects nothing).
// `bgStartMs`/`bgEndMs` are the optional stacked-mix backing window (#2121) —
// a slice just before the voice enters, used to spectral-subtract the earlier
// layers; the service drops the pair unless it forms a valid positive range.
const refSegmentSchema = z.object({
  layerId: str(svc.ID_MAX_LENGTH).optional().default(''),
  startMs: z.number(),
  endMs: z.number(),
  bgStartMs: z.number().optional(),
  bgEndMs: z.number().optional(),
});

// A reference link/video (e.g. a TikTok performance). `url` is required; the
// client renders TikTok urls as embeds and everything else as a link.
// `audioFilename`/`segments` are the optional reference-audio analysis fields
// (#2106) — absent on legacy references; the service omits empty values so
// pre-feature records round-trip unchanged.
const referenceSchema = z.object({
  id: str(svc.ID_MAX_LENGTH).optional(),
  url: str(svc.URL_MAX_LENGTH),
  label: str(svc.LABEL_MAX_LENGTH).optional().default(''),
  note: str(svc.FIELD_MAX_LENGTH).optional().default(''),
  audioFilename: str(svc.URL_MAX_LENGTH).optional(),
  segments: z.array(refSegmentSchema).max(svc.REF_SEGMENTS_MAX).optional(),
  // MuScriptor audio → MIDI transcription of the attached audio (an
  // /api/uploads .mid pointer). The service persists it only alongside an
  // audioFilename — same structural invariant as segments.
  midiFilename: str(svc.URL_MAX_LENGTH).optional(),
});

// No `.default('')` on these fields: `.partial()` (used for PATCH) materializes a
// default for an *omitted* key, which would turn a single-field PATCH into a
// wipe of every other field via updateRound's `'key' in patch` merge. Leaving
// them plain-optional keeps omitted keys absent (preserve) vs present-empty
// (clear); the service's `trimField` coerces a present `undefined`/'' anyway.
const roundInputSchema = z.object({
  title: str(svc.TITLE_MAX_LENGTH).optional(),
  artist: str(svc.ARTIST_MAX_LENGTH).optional(),
  key: str(svc.KEY_MAX_LENGTH).optional(),
  // null clears the tempo; a number is clamped server-side into the band.
  tempo: z.number().int().min(svc.TEMPO_MIN).max(svc.TEMPO_MAX).nullable().optional(),
  rhythmShapeId: str(svc.ID_MAX_LENGTH).optional(),
  notation: str(svc.FIELD_MAX_LENGTH).optional(),
  // Sheet-music notation (PortOS lead-sheet DSL) — bounded free text; the client
  // parses/renders it. Longer cap than `notation` since a full score is verbose.
  score: str(svc.SCORE_MAX_LENGTH).optional(),
  // Harmony variations of the base score (bass, mid/high harmonies). The service
  // drops parts with no notation and defaults the label; the schema bounds the list.
  scoreParts: z.array(scorePartSchema).max(svc.SCORE_PARTS_MAX).optional(),
  notes: str(svc.FIELD_MAX_LENGTH).optional(),
  learned: z.boolean().optional(),
  // Training progress (#1028) — per-scope rolling accuracy history. Optional and
  // absent-tolerant: a legacy/untrained round omits it; the service bounds + clamps.
  progress: progressSchema,
  sections: z.array(sectionSchema).max(svc.SECTIONS_MAX).optional(),
  layers: z.array(layerSchema).max(svc.LAYERS_MAX).optional(),
  recordings: z.array(recordingSchema).max(svc.RECORDINGS_MAX).optional(),
  references: z.array(referenceSchema).max(svc.REFERENCES_MAX).optional(),
  // Ids of other rounds sung together with this one (round-stack partners). The
  // service dedupes and drops self-references; the schema only bounds the list.
  partnerRoundIds: z.array(str(svc.ID_MAX_LENGTH)).max(svc.PARTNERS_MAX).optional(),
});

// AI generate/evaluate inputs. providerId/model are optional overrides; the
// service falls back to the active provider. Empty-string providerId (a UI
// "use default" sentinel) is coerced to undefined so it doesn't pin a bogus id.
const optProvider = z.preprocess((v) => (v === '' ? undefined : v), z.string().optional());
const generateSchema = z.object({
  title: str(svc.TITLE_MAX_LENGTH).optional(),
  artist: str(svc.ARTIST_MAX_LENGTH).optional(),
  brief: str(svc.FIELD_MAX_LENGTH).optional(),
  mood: str(svc.FIELD_MAX_LENGTH).optional(),
  // When true, the target round (route :id) is folded into the prompt so
  // "generate" expands the existing draft instead of starting blank.
  expandExisting: z.boolean().optional(),
  providerId: optProvider,
  model: optProvider,
});
const evaluateSchema = z.object({
  providerId: optProvider,
  model: optProvider,
});
// Derive harmony parts from the round's base score. `partIds` optionally restricts
// which harmony parts to generate (a HARMONY_PARTS id list); the service defaults
// to the full derivable set and only ever derives harmony (never the melody).
const derivePartsSchema = z.object({
  partIds: z.array(str(svc.ID_MAX_LENGTH)).max(svc.SCORE_PARTS_MAX).optional(),
  providerId: optProvider,
  model: optProvider,
});

// Map a service error (carries a `code`) to the right HTTP status. Without
// this, asyncHandler defaults everything to 500.
const mapRoundError = (err) => {
  if (err?.code === svc.ERR_NOT_FOUND) return new ServerError(err.message, { status: 404, code: err.code });
  if (err?.code === svc.ERR_NOT_BUILTIN) return new ServerError(err.message, { status: 400, code: err.code });
  return err;
};
const rethrowRoundError = (err) => { throw mapRoundError(err); };

router.get('/', asyncHandler(async (req, res) => {
  const rounds = await svc.listRounds();
  res.json({ rounds });
}));

router.get('/:id', asyncHandler(async (req, res) => {
  const round = await svc.getRound(req.params.id);
  if (!round) throw new ServerError('Round not found', { status: 404, code: svc.ERR_NOT_FOUND });
  res.json({ round });
}));

// --- Reference-audio import (#2120) -----------------------------------------
// Download + extract audio from a URL via yt-dlp into the uploads dir, so it can
// be attached to a round reference and analyzed exactly like an upload/mic
// capture (the deferred convenience path from #2106; upload/mic stay primary).
// Two-segment `reference-audio/...` paths are registered before `/:id` so the
// literal segment can't be read as a round id. The kickoff returns 202 + a
// jobId; progress streams over SSE; the client persists the returned filename
// on the reference via the normal PATCH on Save.
// `roundId` + `referenceId` (both or neither) name the saved reference the file is
// for, so the server attaches it when the download finishes instead of leaving
// it in the editor's draft until Save (#9943).
const referenceAudioImportSchema = z.object({
  url: str(2048).min(1),
  roundId: str(svc.ID_MAX_LENGTH).min(1).optional(),
  referenceId: str(svc.ID_MAX_LENGTH).min(1).optional(),
}).refine((v) => !v.roundId === !v.referenceId, { message: 'roundId and referenceId must be sent together' });

router.post('/reference-audio/import', asyncHandler(async (req, res) => {
  const { url, roundId, referenceId } = validateRequest(referenceAudioImportSchema, req.body || {});
  res.status(202).json(await startReferenceAudioImport(url, { roundId, referenceId }));
}));

router.get('/reference-audio/import/:jobId/events', (req, res) => {
  if (!attachReferenceAudioSseClient(req.params.jobId, res)) {
    throw new ServerError('Import job not found or expired', { status: 404, code: 'NOT_FOUND' });
  }
});

router.post('/reference-audio/import/:jobId/cancel', (req, res) => {
  res.json({ ok: cancelReferenceAudioImport(req.params.jobId) });
});

// --- Reference-audio → MIDI transcription (MuScriptor) ------------------------
// Transcribe an already-attached reference audio file (an /api/uploads basename)
// into a .mid via the local MuScriptor sidecar. Same job/SSE shape as the import
// above: kickoff returns 202 + a jobId (503 with the install hint when the venv
// isn't provisioned); progress streams over SSE; the client persists the
// returned midiFilename on the reference via the normal PATCH on Save.
const transcribeMidiSchema = z.object({
  filename: str(svc.URL_MAX_LENGTH).min(1),
  model: z.enum(MUSCRIPTOR_MODELS).optional(),
});

router.post('/reference-audio/transcribe-midi', asyncHandler(async (req, res) => {
  const { filename, model } = validateRequest(transcribeMidiSchema, req.body || {});
  // The filename is a stored uploads basename — validate it can't escape the
  // uploads dir (same posture as musicVideo's resolveAudioPath).
  const audioPath = safeUnder(PATHS.uploads, filename);
  if (!audioPath) throw new ServerError('Invalid audio filename', { status: 400, code: 'VALIDATION_ERROR' });
  const outputName = filename.replace(/\.[^.]+$/, '') || 'reference';
  res.status(202).json(await startMidiTranscription({ audioPath, outputName, model }));
}));

router.get('/reference-audio/transcribe-midi/:jobId/events', (req, res) => {
  if (!attachMidiTranscriptionSseClient(req.params.jobId, res)) {
    throw new ServerError('Transcription job not found or expired', { status: 404, code: 'NOT_FOUND' });
  }
});

router.post('/reference-audio/transcribe-midi/:jobId/cancel', (req, res) => {
  res.json({ ok: cancelMidiTranscription(req.params.jobId) });
});

router.post('/', asyncHandler(async (req, res) => {
  const input = validateRequest(roundInputSchema, req.body || {});
  const round = await svc.createRound(input).catch(rethrowRoundError);
  res.json({ round });
}));

router.patch('/:id', asyncHandler(async (req, res) => {
  const patch = validateRequest(roundInputSchema.partial(), req.body || {});
  const round = await svc.updateRound(req.params.id, patch).catch(rethrowRoundError);
  res.json({ round });
}));

router.delete('/:id', asyncHandler(async (req, res) => {
  const result = await svc.deleteRound(req.params.id).catch(rethrowRoundError);
  res.json(result);
}));

// POST /api/rounds/:id/refresh-template → reset a built-in default round's shipped
// content (metadata/lyrics/layers/notation) to the current bundled template,
// preserving the user's own recordings + learned progress. 400 if not built-in.
router.post('/:id/refresh-template', asyncHandler(async (req, res) => {
  const round = await svc.refreshRoundFromTemplate(req.params.id).catch(rethrowRoundError);
  res.json({ round });
}));

// --- AI generate / evaluate -------------------------------------------------
// POST /api/rounds/generate → draft a brand-new arrangement from a brief. Does
// NOT persist — returns { round: <fields>, llm } the client merges/creates from.
// (Routed before /:id/* so a literal `/generate` can't be read as an id.)
router.post('/generate', asyncHandler(async (req, res) => {
  const body = validateRequest(generateSchema, req.body || {});
  const result = await generateRound(body);
  res.json(result);
}));

// POST /api/rounds/:id/generate → expand the stored round (when expandExisting)
// or draft fresh using its title/artist as the brief. Returns { round, llm };
// the client merges into the editor draft (does not auto-save).
router.post('/:id/generate', asyncHandler(async (req, res) => {
  const body = validateRequest(generateSchema, req.body || {});
  const existing = await svc.getRound(req.params.id);
  if (!existing) throw new ServerError('Round not found', { status: 404, code: svc.ERR_NOT_FOUND });
  const result = await generateRound({
    title: body.title ?? existing.title,
    artist: body.artist ?? existing.artist,
    brief: body.brief,
    mood: body.mood,
    existingRound: body.expandExisting ? existing : undefined,
    providerId: body.providerId,
    model: body.model,
  });
  res.json(result);
}));

// POST /api/rounds/:id/evaluate → critique the stored arrangement. Read-only:
// returns { evaluation, llm } without mutating the round.
router.post('/:id/evaluate', asyncHandler(async (req, res) => {
  const body = validateRequest(evaluateSchema, req.body || {});
  const round = await svc.getRound(req.params.id);
  if (!round) throw new ServerError('Round not found', { status: 404, code: svc.ERR_NOT_FOUND });
  const result = await evaluateRound({ song: round, providerId: body.providerId, model: body.model });
  res.json(result);
}));

// POST /api/rounds/:id/derive-parts → derive harmony parts (bass, mid/high
// harmonies) from the round's base melody. Returns { scoreParts, llm }; the
// client merges the parts into the editor draft (does NOT auto-save), matching
// the generate/expand flow. 400 if the round has no base score to derive from.
router.post('/:id/derive-parts', asyncHandler(async (req, res) => {
  const body = validateRequest(derivePartsSchema, req.body || {});
  const round = await svc.getRound(req.params.id);
  if (!round) throw new ServerError('Round not found', { status: 404, code: svc.ERR_NOT_FOUND });
  const result = await deriveRoundParts({
    song: round, partIds: body.partIds, providerId: body.providerId, model: body.model,
  });
  res.json(result);
}));

export default router;