Eve library

ISIS v2 WS08-006: Audio Compliance Checks (Loudness, Clipping, Format Normalization)

Guide

Revision 1

On this page

Scope#

WS08-006 implements first-class audio compliance checks for ISIS audio output packages so downstream systems can deterministically evaluate release readiness for loudness targets, clipping risk, and format normalization.

Research and Existing Implementation Alignment#

Before implementation, existing ISIS audio contract and runtime layers were reviewed to align compliance checks with already-shipped output package infrastructure:

  • Workflow schema and output-package linting:
    • libs/isis/workflows/src/schemas/workflow.schema.ts
    • libs/isis/workflows/src/utils/output-contract-lint.ts
  • Generation runtime output parsing and package assembly:
    • apps/isis/generation-api/src/workflows/types.ts
    • apps/isis/generation-api/src/workflows/executor.ts
  • API/SDK output contracts:
    • apps/isis/generation-api/src/types.ts
    • apps/isis/generation-api/src/schemas/job.schema.ts
    • libs/isis/client/src/types.ts

This ensured compliance reporting extends existing package contracts without introducing schema/runtime drift.

Deliverables#

  1. Workflow schema + lint contract expansion
  • Added optional audio_package.compliance workflow contract.
  • Added compliance artifact inclusion to output package lint bundle derivation.
  • Added compliance artifact id coverage to required artifact consistency checks.
  1. Runtime output-config parsing
  • Extended output spec parser to normalize output_spec.audio_package.compliance into runtime WorkflowOutputConfig.
  • Added normalized compliance settings:
    • loudnessToleranceLufs
    • truePeakToleranceDbtp
    • maxClippingPercent
    • enforceFormatNormalization
    • optional artifactId and pathTemplate
  1. Runtime compliance report emission
  • Extended buildAudioPackageOutput to emit audioPackage.compliance with:
    • loudness check (target vs measured vs tolerance)
    • clipping check (true peak tolerance + estimated clipping percent)
    • format-normalization checks for mixdown, stems, and multi-track artifacts
    • overall compliance status aggregation (pass/warn/fail)
  • Added deterministic compliance artifact output path + metadata.
  1. API/SDK/schema contract updates
  • Added typed compliance report structures to:
    • apps/isis/generation-api/src/types.ts
    • libs/isis/client/src/types.ts
  • Added validation schemas for compliance report payloads in apps/isis/generation-api/src/schemas/job.schema.ts.
  1. Workflow coverage
  • Added audio_package.compliance contracts to:
    • music-cue-composer
    • sfx-sound-designer
    • voice-performance-synthesis
  1. Regression coverage
  • Extended workflow schema tests to include compliance contract acceptance.
  • Extended job output schema tests for compliance payload acceptance and rejection behavior.
  • Extended executor simulation tests to verify compliance report emission and required check structure.

Verification Commands#

bash
pnpm --filter @isis/workflows exec vitest run src/workflows.spec.ts --reporter=dot
pnpm --filter @isis/generation-api exec vitest run src/schemas/job.schema.spec.ts src/workflows/executor.spec.ts --reporter=dot
node scripts/isis/generate-v2-workflow-taxonomy-registry.mjs
node scripts/isis/validate-v2-workflow-taxonomy-registry.mjs
node scripts/isis/validate-v2-compliance-gate.mjs

Result#

WS08-006 is now implemented as a typed, validated, and runtime-emitted audio compliance report contract covering loudness, clipping, and format normalization across audio workflow families and API/SDK surfaces.