SongData

Song metadata, chart, and music data structures

The SongData module defines the structure for song information, charts, and metadata in Friday Night Funkin’.

Core Classes

SongMetadata

Contains information about a song for display in Freeplay and loading chart assets.

version · Version · required

Semantic versioning string for the song data format

songName · String · default: "Unknown"

Display name of the song

artist · String · default: "Unknown"

Artist who created the song

charter · String

Person who charted the song

divisions · Int · default: "96"

Grid divisions for charting

looped · Bool · default: "false"

Whether the song should loop

offsets · SongOffsets

Instrumental and vocal offsets relative to the chart

playData · SongPlayData · required

Data relating to the song’s gameplay

generatedBy · String · required

Tool or editor that generated the file

timeFormat · SongTimeFormat · default: "ms"

Time format used in the chart: "ticks", "float", or "ms"

timeChanges · Array<SongTimeChange> · required

Array of tempo and time signature changes

SongPlayData

Defines gameplay-specific song data.

songVariations · Array<String> · default: "[]"

Available variations of the song (e.g., "erect", "pico")

difficulties · Array<String> · required

Available difficulties for this song

characters · SongCharacterData · required

Characters used in the song

stage · String · required

Stage ID to use for this song

noteStyle · String · required

Note skin to use

ratings · Map<String, Int> · default: "{normal: 0}"

Difficulty ratings as displayed in Freeplay (key is difficulty ID)

album · String

Album ID to display in Freeplay

stickerPack · String

Sticker pack for transitions

previewStart · Int · default: "0"

Audio preview start time in milliseconds

previewEnd · Int · default: "15000"

Audio preview end time in milliseconds

SongCharacterData

Information about characters used in a song variation.

player · String · default: "''"

Player character ID (usually Boyfriend)

girlfriend · String · default: "''"

Girlfriend/spectator character ID

opponent · String · default: "''"

Opponent character ID

instrumental · String · default: "''"

Instrumental variant to use

altInstrumentals · Array<String> · default: "[]"

Alternative instrumental variants available

opponentVocals · Array<String>

Character IDs for opponent vocals

playerVocals · Array<String>

Character IDs for player vocals

SongChartData

Contains chart data for notes and events.

version · Version · required

Semantic versioning string for chart data format

scrollSpeed · Map<String, Float> · required

Scroll speeds per difficulty

events · Array<SongEventData> · required

Song events (camera focuses, animations, etc.)

notes · Map<String, Array<SongNoteData>> · required

Note data per difficulty

generatedBy · String · required

Tool that generated the chart

SongNoteData

Represents a single note in the chart.

t · Float · required

Timestamp in the song’s time format

d · Int · required

Note data index. 0-3 for directions (left, down, up, right). floor(d / 4) determines strumline (0 = player, 1 = opponent)

l · Float · default: "0"

Length for hold notes (0 for tap notes)

k · String

Note kind for custom behavior (e.g., "mine", "ghost")

p · Array<NoteParamData> · default: "[]"

Custom parameters for note kinds

SongEventData

Represents a song event.

t · Float · required

Timestamp in the song’s time format

e · String · required

Event kind (e.g., "FocusCamera", "PlayAnimation")

v · Dynamic

Event value/data (structure depends on event kind)

SongTimeChange

Defines tempo and time signature changes.

t · Float · required

Timestamp of the time change

bpm · Float · required

Quarter notes per minute

n · Int · default: "4"

Time signature numerator

d · Int · default: "4"

Time signature denominator (should be power of 2)

b · Float

Beat time for linear calculation

bt · Array<Int> · default: "[4, 4, 4, 4]"

Beat tuplets defining step divisions per beat

SongOffsets

Offsets to correct timing relative to the chart.

instrumental · Float · default: "0"

Instrumental offset in milliseconds. Negative values start earlier, positive values add silence

altInstrumentals · Map<String, Float> · default: "{}"

Offsets for alternate instrumentals

vocals · Map<String, Float> · default: "{}"

Vocal offsets per character, applied on top of instrumental offset

altVocals · Map<String, Map<String, Float>> · default: "{}"

Vocal offsets per character for alternate instrumentals

Example: Song Metadata

{
  "version": "2.0.0",
  "songName": "Tutorial",
  "artist": "Kawai Sprite",
  "charter": "MasterEric",
  "timeFormat": "ms",
  "timeChanges": [
    {
      "t": 0,
      "bpm": 100,
      "n": 4,
      "d": 4
    }
  ],
  "playData": {
    "songVariations": [],
    "difficulties": ["normal"],
    "characters": {
      "player": "bf",
      "girlfriend": "gf",
      "opponent": "gf",
      "instrumental": ""
    },
    "stage": "mainStage",
    "noteStyle": "funkin",
    "ratings": {
      "normal": 1
    }
  },
  "generatedBy": "Funkin' Crew Chart Editor"
}

Example: Chart Data

{
  "version": "2.0.0",
  "scrollSpeed": {
    "normal": 1.0
  },
  "events": [
    {
      "t": 1000,
      "e": "FocusCamera",
      "v": {
        "char": 1
      }
    }
  ],
  "notes": {
    "normal": [
      {
        "t": 2000,
        "d": 0,
        "l": 0
      },
      {
        "t": 2500,
        "d": 1,
        "l": 200
      }
    ]
  },
  "generatedBy": "Funkin' Crew Chart Editor"
}