Song Spec Sheet

← Back to Index · ← Vendetta Visual Stream

Purpose

song.spec.yaml defines a deterministic track scenario for vendetta-engine.

Use it when you want repeatable playback behavior without relying on live audio analysis. In the stream contract, this maps to stream.meta.playback_started.source = spec.

File Shape

Top-level keys:

  • version
  • track
  • timing
  • engine
  • story_labels
  • segments
  • output_expectations

Field Reference

version

  • version: schema version. Current value: 1.

track

  • id: stable identifier for the track spec.
  • title: display title.
  • artist: display artist.
  • notes: optional notes about purpose or test scope.

timing

  • bpm_mode: fixed | auto.
  • bpm: required when bpm_mode=fixed.
  • beats_per_bar: usually 4.

engine.thresholds

  • presence_open_beats
  • presence_close_beats
  • variance_confirm_bars
  • sustain_confirm_bars
  • weight_band_confirm_bars

These define the temporal confirmation behavior used by the story engine.

engine.source_blend

  • enabled: boolean
  • threshold_scale_factor: number (default 1.5)
  • crossfader_curve: aggressive | linear | gentle
  • audio_fallback: boolean

These fields control blend-aware threshold widening and fallback blend estimation behavior.

engine.weight_hysteresis

  • medium_to_light_down
  • light_to_medium_up
  • medium_to_heavy_up
  • heavy_to_medium_down

These prevent weight-band flicker near boundaries.

story_labels

  • naming: naming strategy. Current expected value: explicit_technical.
  • examples: optional list of representative labels (for docs/readability).

segments[]

Each segment describes a deterministic musical window.

Required per segment:

  • id
  • beats
  • start_weight, end_weight (0..1)
  • start_presence, end_presence (0..1)
  • sustain: dry | mid | wet | reverse
  • variance_direction: rising | stable | falling
  • start_magnitude, end_magnitude (0..1)
  • expected_story_hint: expected story label (for sanity checks)

Optional blend fields per segment:

  • source_blend_start (0..1, default 0.0)
  • source_blend_end (0..1, default 0.0)
  • source_blend_peak_beat (integer, default unset)
  • source_blend_reliable (boolean, default true)

output_expectations

  • stream_types: expected stream families (for example meta, frame, transition)
  • required_frame_fields: fields consumers can depend on in frame payloads

Example song.spec.yaml

# song.spec.yaml
version: 1

track:
  id: "seraj_test"
  title: "Seraj Test Track"
  artist: "Unknown"
  notes: "Single-source local testing spec."

timing:
  bpm_mode: fixed          # fixed | auto
  bpm: 128.0              # required when bpm_mode=fixed
  beats_per_bar: 4

engine:
  thresholds:
    presence_open_beats: 4
    presence_close_beats: 2
    variance_confirm_bars: 2
    sustain_confirm_bars: 2
    weight_band_confirm_bars: 2

  source_blend:
    enabled: true
    threshold_scale_factor: 1.5
    crossfader_curve: aggressive
    audio_fallback: true

  weight_hysteresis:
    medium_to_light_down: 0.30
    light_to_medium_up: 0.38
    medium_to_heavy_up: 0.70
    heavy_to_medium_down: 0.62

story_labels:
  naming: explicit_technical
  examples:
    - groove_heavy_mid
    - escalation_heavy_reverse
    - build_medium_dry
    - fade_light_wet
    - absence

segments:
  - id: intro_lock
    beats: 16
    start_weight: 0.76
    end_weight: 0.78
    start_presence: 0.92
    end_presence: 0.90
    sustain: mid                    # dry|mid|wet|reverse
    variance_direction: stable      # rising|stable|falling
    start_magnitude: 0.08
    end_magnitude: 0.12
    expected_story_hint: groove_heavy_mid

  - id: build_up
    beats: 16
    start_weight: 0.78
    end_weight: 0.84
    start_presence: 0.90
    end_presence: 0.86
    sustain: mid
    variance_direction: rising
    start_magnitude: 0.30
    end_magnitude: 0.85
    expected_story_hint: escalation_heavy_mid

  - id: breakdown
    beats: 8
    start_weight: 0.80
    end_weight: 0.79
    start_presence: 0.06
    end_presence: 0.04
    sustain: mid
    variance_direction: rising
    start_magnitude: 0.80
    end_magnitude: 0.95
    expected_story_hint: absence

  - id: reverse_build
    beats: 4
    start_weight: 0.81
    end_weight: 0.84
    start_presence: 0.90
    end_presence: 0.88
    sustain: reverse
    variance_direction: rising
    start_magnitude: 0.70
    end_magnitude: 0.95
    expected_story_hint: escalation_heavy_reverse

  - id: return_groove
    beats: 16
    start_weight: 0.82
    end_weight: 0.78
    start_presence: 0.95
    end_presence: 0.90
    sustain: dry
    variance_direction: stable
    start_magnitude: 0.25
    end_magnitude: 0.18
    source_blend_start: 0.7
    source_blend_end: 0.0
    source_blend_peak_beat: 4
    source_blend_reliable: true
    expected_story_hint: groove_heavy_dry

  - id: wind_down
    beats: 16
    start_weight: 0.70
    end_weight: 0.45
    start_presence: 0.88
    end_presence: 0.76
    sustain: mid
    variance_direction: falling
    start_magnitude: 0.30
    end_magnitude: 0.10
    expected_story_hint: cool_medium_mid

output_expectations:
  stream_types:
    - meta
    - frame
    - transition
  required_frame_fields:
    - beat
    - bar
    - bpm
    - story
    - story_struct.phase
    - foundation.weight
    - foundation.presence
    - sustain
    - variance.direction
    - variance.magnitude
    - source_blend
    - source_blend_reliable
    - calibration
    - effective_thresholds

Implementation Notes

  • expected_story_hint is advisory. Actual story still depends on engine confirmation rules.
  • absence remains outside the story matrix and should be handled explicitly.
  • segments should be contiguous in playback order.
  • Keep values normalized to 0..1 where defined to match frame consumers.
  • Live calibration still applies during source=spec playback; the spec controls input while calibration controls interpretation.