Eve library

ISIS v2 WS08-002: Audio Output Package Contract

Guide

Revision 1

On this page

Scope#

WS08-002 introduces a first-class audio output package contract covering:

  • mixdown/master delivery
  • optional stem delivery and stem archive bundles
  • loudness analysis metadata
  • cue-sheet timeline metadata

The contract is now available across workflow schema, lint/contract derivation, runtime execution output, API schemas, and SDK types.

Research and Existing Implementation Alignment#

Before implementation, existing contract patterns and audio metadata structures were reviewed and reused:

  • Structured package pattern from three_d_package and editorial_package.
  • Output package lint derivation/validation pattern from workflow output contract utilities.
  • Existing audio metadata models from provider integrations for sample rate/bit-depth/loudness conventions.

Deliverables#

  1. Workflow schema extension (output_spec.audio_package)
  • Added typed audio package blocks:
    • mixdown
    • stems (+ optional archive)
    • loudness
    • cue_sheet
  • Added new audio enums/constraints:
    • stem types
    • mixdown formats (wav, flac, aiff)
    • bit depth (16, 24, 32)
    • loudness standards
    • cue sheet formats (csv, json, cue)
  • Added validation gates:
    • audio outputs require audio_package
    • audio_package only allowed for audio outputs
  1. Workflow contract lint derivation
  • Added auto-derivation of required/optional artifacts from output_spec.audio_package.
  • Added lint checks verifying expected audio package artifact IDs are emitted in resolved output contracts.
  1. Audio workflow definitions updated
  • sfx-sound-designer
  • voice-performance-synthesis
  • music-cue-composer

Each now declares explicit audio_package contracts for mixdown, stems, loudness report, and cue sheet artifacts.

  1. Runtime/API/SDK contract propagation
  • Added audioPackage to runtime workflow output config parsing.
  • Added JobOutput.audioPackage in generation API types and zod schemas.
  • Added mirrored audioPackage types in client SDK contracts.
  • Implemented runtime assembly of audioPackage outputs in both real and simulated execution paths.
  1. Test coverage
  • Workflow schema tests for valid/invalid audio package contracts.
  • Job output schema tests for audio package acceptance/rejection.
  • Executor simulation test confirming audio package emission for music workflow runs.

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

Result#

WS08-002 is now implemented as a first-class, validated audio package contract with end-to-end runtime/API/SDK exposure.