Skip to main content
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"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us