Recipe catalog / tension-level

Grade harmonic tension

How much harmonic tension does the current point in progression carry, from fully resolved to a peak demanding resolution, given any key supplied?

A generation loop or accompaniment engine wants to know whether the harmony is at rest, building, or begging for resolution, so it can decide whether to release, hold, or push further.

Explore this recipe interactively · Source and implementation guide

Use tension-level in TypeScript

Install with npm install jev-recipes. Requires Node.js 22.9 or newer and ES modules. Set TYPESAFE_API_KEY in your server environment for live calls, which send input to TypeSafe and use API quota. See the installation guide.

import { tensionLevel } from 'jev-recipes/tension-level';

const result = await tensionLevel({
  "progression": "Am - F - Dm7 - G7 - G7(b9) with the melody suspended on C over the bass, held for two full bars and swelling (current chord)",
  "key": "C major",
  "minConfidence": 0.8
});
console.log(result);

Input contract

{
  "input": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "progression": {
        "type": "string"
      },
      "key": {
        "type": "string"
      },
      "minConfidence": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      }
    },
    "required": [
      "progression"
    ]
  },
  "result": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "model": {
        "type": "string"
      },
      "usage": {
        "type": "object",
        "properties": {
          "input_tokens": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "output_tokens": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "input_tokens",
          "output_tokens"
        ],
        "additionalProperties": false
      },
      "status": {
        "type": "string",
        "enum": [
          "ready",
          "review"
        ]
      },
      "score": {
        "type": "number",
        "minimum": 0
      },
      "level": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991
      },
      "confidence": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      },
      "probabilities": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      },
      "tension": {
        "type": "string",
        "enum": [
          "resolved",
          "low",
          "moderate",
          "high",
          "peak"
        ]
      }
    },
    "required": [
      "model",
      "usage",
      "status",
      "score",
      "level",
      "confidence",
      "probabilities",
      "tension"
    ],
    "additionalProperties": false
  }
}

Saved example result

This hand-authored response demonstrates the contract. It is not a model accuracy measurement. Run it without an API key: npx jev-recipes demo tension-level.

{
  "model": "demo-fixture",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0
  },
  "status": "ready",
  "score": 3.76,
  "level": 4,
  "confidence": 0.83,
  "probabilities": {
    "0": 0.01,
    "1": 0.01,
    "2": 0.02,
    "3": 0.13,
    "4": 0.83
  },
  "tension": "peak"
}

Evaluation evidence

Use the evaluation guide to measure this decision on your own labeled cases.

Limitations

• Grades the tension implied by chord symbols and annotations at the last point in progression. It does not analyze voicings, compute scale degrees, or identify the key; supply key and describe suspensions or holds in the text.
• Tension is heard relative to a style; a dominant seventh that demands resolution in a hymn is a resting chord in a blues. State the style in the text when it matters.
• The grade is not a decision about what to play next.

Related recipes

• urgency-signal: Use urgency-signal to detect an explicit request for urgent attention in a message, not the pull of an unresolved chord.
• step-progress: Use step-progress to judge whether a new observation advances a task objective, rather than how far a harmony is from its home chord.