Sheet format reference · Jianpu 简谱 → JSON
The guzheng sheet JSON format
Online Guzheng plays numbered notation stored as a small JSON file. The whole format is one object with a measures array — here is every field, a worked example, and a prompt you can hand to an AI along with a photo of your sheet.
Three steps to a playable sheet
- Give any AI assistant the prompt below together with a photo or PDF of your jianpu sheet.
- Save the JSON it returns as a
.jsonfile. - Open the guzheng, switch to 🎼 Sheet Play and click 📂 Upload JSON sheet.
Nothing is uploaded to a server. The file is parsed in your browser and kept in local storage so it is still there next time. You can also build a sheet by hand in ✏️ Sheet Editor and export it as JSON.
A complete example
Two measures — an ascending pentatonic bar, then a tremolo, a rest and one note an octave up.
{
"version": 1,
"title": "Pentatonic Warm-Up",
"artist": "Your name (optional)",
"key": "D",
"tempo": 88,
"timeSignature": "4/4",
"measures": [
{ "notes": [
{ "degree": 1, "beats": 1 },
{ "degree": 2, "beats": 1 },
{ "degree": 3, "beats": 1 },
{ "degree": 5, "beats": 1 }
] },
{ "notes": [
{ "degree": 6, "beats": 2, "technique": "tremolo" },
{ "degree": 0, "beats": 1 },
{ "degree": 1, "octave": 1, "beats": 1 }
] }
]
}Top-level fields
| Field | Type | Meaning |
|---|---|---|
version | number | Always 1. Reserved for future format changes. |
title | string | Shown above the sheet. Falls back to “Untitled sheet”. |
artist | string, optional | Composer, arranger or source. Displayed next to the title. |
key | string, optional | The letter from the 1=D marking — “D”, “G”, “Bb”, “F#”. The app transposes the whole instrument to match, up to 7 semitones either way. |
tempo | number | Beats per minute, 20–300. Missing or invalid values become 80 with a warning. |
timeSignature | string, optional | As printed, e.g. “4/4” or “2/4”. Sets the barline count; defaults to 4/4. |
youtube | object, optional | { "videoId": "…" } — an 11-character id or a full YouTube URL. Loads the karaoke beat panel. |
measures | array, required | One entry per printed measure: { "notes": [ … ] }. Must not be empty. |
Note fields
Each entry of measures[n].notes is one printed note or rest, in reading order.
| Field | Type | Meaning |
|---|---|---|
degree | integer 0–7 | The printed jianpu digit. 0 is a rest. 4 and 7 are played by press-bending strings 3 and 6 — write them exactly as printed. |
octave | integer −2…2, optional | Dots above the digit → 1 (two dots → 2). Dots below → −1 (two dots → −2). Omit for the middle octave. |
beats | number 0–16, optional | Length in quarter-note beats. Defaults to 1. Bad values become 1 with a warning. |
technique | string, optional | Currently only "tremolo" (摇指). Anything else is ignored. |
Degrees and strings
The instrument is tuned D pentatonic — D, E, F♯, A, B repeating across 21 strings. Jianpu 4 and 7 have no string of their own; the app plays them by press-bending the green 3 and 6 strings, exactly as a player would. Write 4 and 7 normally and the app handles it.
| Degree | Pitch (key of D) | How it is played | String colour |
|---|---|---|---|
| 1 | D | string 1 of each group | — |
| 2 | E | string 2 of each group | — |
| 3 | F♯ | string 3 of each group | green |
| 4 | G | press-bend from 3 (+1 semitone) | green |
| 5 | A | string 4 of each group | — |
| 6 | B | string 5 of each group | green |
| 7 | C♯ | press-bend from 6 (+2 semitones) | green |
A degree that lands outside the 21-string range is shown in red on the sheet and skipped during playback, with a warning above the panel. Lower the octave value or transpose with Tuning.
Reading rhythm into beats
beats counts quarter-note beats, so it maps directly onto the underlines, dashes and dots of printed jianpu. Merge tied notes into a single note with the summed value.
| Printed | Name | beats |
|---|---|---|
| 5 | plain digit | 1 |
| 5 — | one dash | 2 |
| 5 — — | two dashes | 3 |
| 5· | dotted | 1.5 |
| 5 (one underline) | eighth | 0.5 |
| 5 (one underline, dotted) | dotted eighth | 0.75 |
| 5 (two underlines) | sixteenth | 0.25 |
Prompt for converting a sheet with an AI
Copy this, paste it into ChatGPT, Claude, Gemini or any other assistant, and attach a clear photo or PDF of the jianpu page. It is the same specification as above, written for a model.
Convert the attached jianpu (简谱, numbered musical notation) sheet music for guzheng into JSON.
Output ONLY a single JSON object — no commentary, no markdown code fence — with exactly this shape:
{
"version": 1,
"title": "song title as printed",
"artist": "composer / source (optional)",
"key": "D",
"tempo": 88,
"timeSignature": "4/4",
"measures": [
{ "notes": [
{ "degree": 3, "octave": 0, "beats": 1 },
{ "degree": 5, "beats": 0.5 },
{ "degree": 6, "beats": 0.5, "technique": "tremolo" },
{ "degree": 1, "octave": 1, "beats": 2 }
] },
{ "notes": [
{ "degree": 0, "beats": 1 },
{ "degree": 6, "octave": -1, "beats": 3 }
] }
]
}
Rules:
- One entry in "measures" per printed measure. Split at every barline, reading left to right, top row to bottom row.
- "degree": the printed digit 1–7. Use 0 for a rest.
- "octave": dots above the digit → 1 (two dots → 2). Dots below → -1 (two dots → -2). No dots → 0 (or omit).
- "beats": length in quarter-note beats. Bare digit = 1. One underline = 0.5, two underlines = 0.25. A small dot after the digit makes it 1.5× (dotted note, e.g. 1.5). Each dash "—" after a digit adds 1 beat (so "5 — —" = beats 3). Merge tied notes into one note with the summed beats.
- "key": from the "1=D" marking — the letter only, e.g. "D", "G", "Bb", "F#". The app auto-tunes to it.
- "tempo": the metronome marking (♩=88). If missing, estimate from the tempo word.
- "timeSignature": as printed, e.g. "4/4" or "2/4".
- "technique": optional. Use "tremolo" on notes marked 摇指 / tremolo. Omit otherwise.
- Optionally add "youtube": { "videoId": "11-char id" } if a backing/karaoke video is known.
- Grace notes and ornaments: skip them, keep only the main melody notes. For chords, keep the top (melody) note.
- Do not transpose anything — copy the digits exactly as printed. Degrees 4 and 7 are fine: the app plays them by press-bending strings 3 and 6.Models misread crowded scans. Load the result, listen once with 👂 Listen, and fix anything wrong in ✏️ Sheet Editor before practising.
Please only convert sheets you may legally use
Sheet music is copyrighted like any other work. Convert music you wrote, music you have a licence for, or traditional and public-domain pieces — and keep the result to yourself unless the rights allow otherwise. This site hosts no third-party sheet music and never uploads yours: your file stays in your own browser.
The bundled demo and every exercise in Lessons is original material written for this site, free for you to use.