Pick the next melody note

Which candidate note best continues the melody in recentNotes, given any key and style supplied?

A generation loop such as an infinite piano player has produced the last few notes, application code has enumerated a handful of legal next notes, and you want a musical judgment of which one continues the line best, or whether a rest is better.

Explore this recipe interactively · Source and implementation guide

Use next-note 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 { nextNote } from 'jev-recipes/next-note';

const result = await nextNote({
  "recentNotes": "C4 E4 G4 E4 D4",
  "key": "C major",
  "style": "gentle lullaby",
  "candidates": [
    {
      "id": "c5",
      "text": "C5 (octave leap up to the tonic)"
    },
    {
      "id": "b3",
      "text": "B3 (leading tone just below)"
    }
  ],
  "minConfidence": 0.8
});
console.log(result);

Input contract

Field	Type	Needed
recentNotes	string	Required
candidates	array	Required
key	string	Optional
style	string	Optional
minConfidence	number	Optional

Full input and result schemas

{
  "input": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "recentNotes": {
        "type": "string"
      },
      "candidates": {
        "minItems": 1,
        "maxItems": 50,
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "text": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "text"
          ]
        }
      },
      "key": {
        "type": "string"
      },
      "style": {
        "type": "string"
      },
      "minConfidence": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      }
    },
    "required": [
      "recentNotes",
      "candidates"
    ]
  },
  "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"
        ]
      },
      "verdict": {
        "type": "string",
        "enum": [
          "matched",
          "none",
          "ambiguous"
        ]
      },
      "selection": {
        "type": [
          "string",
          "null"
        ]
      },
      "suggestedSelection": {
        "type": [
          "string",
          "null"
        ]
      },
      "confidence": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      },
      "probabilities": {
        "type": "object",
        "properties": {
          "candidates": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            }
          },
          "none": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "ambiguous": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          }
        },
        "required": [
          "candidates",
          "none",
          "ambiguous"
        ],
        "additionalProperties": false
      }
    },
    "required": [
      "model",
      "usage",
      "status",
      "verdict",
      "selection",
      "suggestedSelection",
      "confidence",
      "probabilities"
    ],
    "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 next-note.

{
  "model": "demo-fixture",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0
  },
  "status": "ready",
  "verdict": "matched",
  "selection": "b3",
  "suggestedSelection": "b3",
  "confidence": 0.9,
  "probabilities": {
    "candidates": {
      "c5": 0.05,
      "b3": 0.9
    },
    "none": 0.03,
    "ambiguous": 0.02
  }
}

Evaluation evidence

Fixture only

No verified live accuracy measurement is available. Evaluate representative cases before using this decision in your workflow.

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

Limitations

Judges melodic sense from note names and descriptions. It does not verify that a candidate is in the key or compute intervals exactly; do those checks in application code before supplying candidates.
Taste in a style is a judgment, not a rule. Two runs on the same input can prefer different candidates when they fit similarly well.
A pick says nothing about duration, dynamics, or harmony under the note; supply or decide those separately.

Related recipes

game-action: Use game-action when the choice is among generic JSON game actions rather than notes judged for melodic sense.
choose-action: Use choose-action when an explicit goal and rulebook govern the pick instead of melodic continuity in a key and style.