# Documentation **Table of Contents** - [1. Getting Started](#1-getting-started) - [2. Managing Scores](#2-managing-scores) - [2.1. Creating and Saving](#21-creating-and-saving) - [2.2. Locking Edits](#22-locking-edits) - [3. Score Information](#3-score-information) - [3.1. Score Information](#31-score-information) - [3.2. Musical Elements](#32-musical-elements) - [3.3. LilyPond Scripting](#33-lilypond-scripting) - [4. Writing Music in Shorthand](#4-writing-music-in-shorthand) - [4.1. Notes Notation](#41-notes-notation) - [4.2. Finger placements for left hand](#42-finger-placements-for-left-hand) - [4.3. Finger placements for right hand](#43-finger-placements-for-right-hand) - [4.4. Vibratos and Slides](#44-vibratos-and-slides) - [4.5. Bars, Glissandos, Ties](#45-bars-glissandos-ties) - [4.6. Multi-Voice Scores](#46-multi-voice-scores) - [5. Writing Music in JianZiPu](#5-writing-music-in-jianzipu) ## 1. Getting Started #### Example ([link](/nltabs/8oxs3oT)) If you want to read in detail about the snippet above, I encourage you to [check out the Getting Started page](/gettingstarted.html). You can also [take a look at the Glossary](/nltabs/qbSWqqt) for examples of the techniques mentioned here compiled together in one place. ## 2. Managing Scores ### 2.1. Creating and Saving Create scores for the Guqin using NLTabs schema with this site. You can save your tabs, and share them with others Create new scores by clicking "New" at the top. When you save a score (click "Save" in the navigation), we will automatically save a version. If you save again, the version will increment. If you use the url to your score with out the version tag, then we will automatically load the latest version. You can click "Save As" in the navigation to save to a new url starting at version 1. Any un-saved entries for the shorthand notation in the last piece you edit will be saved locally. You will see an asterik next to the Save button in the header. When you reload that piece (this only works for the latest piece you edited), you will be prompted whether you want to load the unsaved version or the last saved version. ### 2.2. Locking Edits You can lock your score with a password so that only you can edit the score. Once you set a password, only those with the password can save and increment the versions. Others can still view the score (if they have the link), and they can copy your score to a new link using the "Save as New" feature. You can always unlock your score as long as you have the password. ## 3. Score Information ### 3.1. Score Information Following should only be at the top of the score once. #### Example ``` title: Variations on a Theme composer: Ada Lovelace tuning: g,, a,, c, d, e, g, a, temperament: equal showtimesig: none bars: auto ``` #### Definitions All of these are optional and have default values, but you should probably really consider being explicity about tuning at least. * **title**: (*default: blank*) the title of the piece, this appears front and center on the score. Use `\n` to indicate a new line. * **composer**: (*default: blank*) appears on the right side under the title. Use `\n` to indicate a new line. * **tuning**: (*default: g, a, c d e g a*) use the Lilypond format with spaces in between the notes (notes are lowercase). This will appear on the left side under the title, and it will drive the positioning of notes in the score. * **tuninglabel**: (*default: whatever the tuning is*) Use this if you want a custom string of text in the left side under the title (where tuning info is traditionally). Use `\n` to indicate a new line. * **temperament**: (*default: `equal`*) two values here are `just` and `equal`. These temperament settings dictate what the hui position numbers will be.. *slightly* ([example of just](/nltabs/yaRbv2P), [example of equal](/nltabs/xGkkS1I)). For a deep dive into what this is and why the small changes in hui positions, [check out my blog post](https://blog.nyl.io/guqin-part-2-open-and-pressed-notes/) on this topic. * **showtimesig**: (*default: `yes`*) if `no`, then the score will omit any time signatures. * **bars**: (*default: `manual`*) if `auto`, then the score will auto insert bars based on the time signatures. If `manual`, then you will need to manually type in bars using the `|` character ([more bar notations here](#45-bars-glissandos-ties)). ### 3.2. Musical Elements These can appear multiple times in the score as needed. #### Example ``` key: c major time: 2/4 clef: treble tempo: 4 = 60 mark: section 1 // lorem ipsum ``` #### Definitions These are all optional. * **key**: (*default: c major*) This is the key, you can write signatures like `c minor`, `b- major` (b-flat major), `b# minor` etc. * **time**: (*default: 4/4*, shown as C or common time) This is the time signature. Valid notations are 2/4, 3/4, etc using Lilypond's time signature notation. * **clef**: (*default: bass*) Valid values are bass, treble, alto, tenor. * **tempo**: (*default: 4=60*, not visible on the score) This appears above the staff and also effects the tempo of the MIDI file. Notations uses Lilypond's tempo notation, so 4=60 is quarter note at 60 beats per minute (bpm). Default is 4=60 * **mark**: Add when needed for text to appears above the staff in the score. * **comments (begin like with `//`)**: Add when needed, this does not appear anywhere in the score. ### 3.3. LilyPond Scripting You can also add custom LilyPond script. Please only do this if you know what you are doing. You can do this in two ways. First way: in the shorthand portion, you can insert custom LilyPond script by starting a line with the `ly:` tag. Second way: you can convert to LilyPond Code, and then edit the raw code in the LilyPond tab. ## 4. Writing Music in Shorthand Now we get to the fun part. Here's how to write music in Guqin Shorthand. I found it easiest to have music come in two lines. The first is the notes line, prefaced by `n:`. This mostly contains information on the pitch and beat values. Basicallly, it's the stuff western music tends to focus on (and what I'm personally used to reading as a piano player). The second coupling is the finger placement, prefaced by `f:`. This is mostly what is contained in the traditional guqin notation, such as which string to play, which finger to use to pluck, whether to pluck in wards or outwards, etc. ### 4.1. Notes Notation Lines preface with `n:` are notes. Notes are written in LilyPond style. | shorthand | description | | ------------------- | --------------------------------------------------| | `a` to `g` | notes when string is pressed or open | | `A` to `G` (capitalized) | Fanyin Notes | | `-` | flats, used after the note (ex: `c-` is c flat) | | `#` | sharps, used after the note (ex: `c#` is c sharp) | | `r` | rest | | `R` | hidden rest | | `1-64` | 1 = whole notes, 4 quarter, etc.
NOTE: notes in the chord must be ordered from lowest to highest string
(lowest string is furthest away from the player) | | `fraction{...}` | fraction represents a tuplet, `3/2{c8 c c}` is a triplet spanning one beat, for example | | `.` (period) | dot indicate half notes, so `2.` equals three beats | | `,` (comma) | lower octave, `,,` is double lower octave, etc. | | `'` (single quote) | higher octave, `''` is double lower octave, etc. | | ex: `c,e,` | two notes together with no space forms a chord. | #### Example ([link](/nltabs/IJurYx2)) For Fan Yin notes (harmonics), you can achieve the same note using different positions, or by placing your finger on different huis. You can read all about the physics of it [in my blog post on harmonics](https://blog.nyl.io/guqin-part-1-harmonics-and-hui/), if you are interested. Not every note has the same number of hui variations, but if you render a Fan Yin that isn't the right hui, you can specify a specific hui using parentheses (e.g., `(9)` represents the 9th hui). The default hui will be somewhere close to the 7th hui and closer to the player. #### Example ([link](/nltabs/y6WJHEo)) ### 4.2. Finger placements These are lines prefaced with `f:`. If you enclose these in \[\[double brackets\]\], then some of these will appear as jianzipu notation. | shorthand | translates when in \[\[brackets\]\] | **descriptions** | | ----------------- | -------------- | -------------------------------------------------------------- | | `1` to `7` | | string number, `1` is outwardmost string, `7` is inwardmost string | | `0` | | rest | | `sdfv` | [[sdfv]] | left hand press, pinky, ring, etc. (`a` works for pinky, but not really used) | | `w`, `g` | | left hand knuckle presses (`w` for ring, `g` for thumb) | | `x` | [[x]] | left hand press with the outer ring knuckle, "kneeling" | | `c` | | left hand pluck inwards | | `e` | | left hand middle finger push out | | `SDFV` | | left hand mute/press (`A` also works for pink, not used) | #### Example ([link](/nltabs/RTtEvuu)) If you want to add custom notations in the left hand position below the staff, you can write `(lh:blahblah)`. This will replace any other notation for that note. Use `_` (underscore) to represent a space since otherwise, the space will be interpreted as a separate note. #### Example ([link](/nltabs/f6uQCKj)) ### 4.3. Finger placements for right hand If repetitive fingers are used (e.g., `3v 3v`), then the score will automatically abridge the notation in the score to (`3v v`). This is only a feature for scores with single voices. Multi-voice scores get much more complicated and we'll just always show the finger number in the right hand. | shorthand | translates when in \[\[brackets\]\] | **descriptions** | | ------------- | --------- | -------------------------------------------------------------- | | `njkl` | [[njkl]] | right hand pluck inwards, thumb, index etc. | | `huio ` | [[huio]] | right hand pluck outwards, thumb, index, etc. | | `H` | [[H]] | cuo (second and third finger towards center) | | `U` | [[U]] | fan cuo (second and third finger towards outside) | | `I` | [[I]] | da cuo (thumb and third finger towards center) | | `O` | [[O]] | da fan cuo (thumb and third finger outwards) | | `!` | | override such that right hand fingering are always displayed | #### Example ([link](/nltabs/yrZLlXz)) If you want to add custom notations in the right hand position above the staff, you can write `(rh:blahblah)`. This will replace any other notation for that note. Use `_` (underscore) to represent a space since otherwise, the space will be interpreted as a separate note. #### Example ([link](/nltabs/swDyrl5)) ### 4.4. Vibratos and Slides | shorthand | **descriptions** | | ----------------- | -------------------------------------------------------------- | | `-` | indicates a slide (should be it's own note) | | `~` | indicates a vibrato (should be attached after a note) | | `/` | slide up to note (should be attached to a note) | | `\` | slide down to note (attached to note) | #### Example ([link](/nltabs/eni1l9o)) ### 4.5. Bars, Glissandos, Ties These elements are needed in both the `n:` and `f:` lines. Failure to have these lines match will result in errors. In the example below, you see where there's a bar in the `n:` line, for example, there's also a bar in the `f:` line. | shorthand | description | | ----------| ----------------------------------- | | `\|` | bar | | `\|\|` | double bar | | `\|.` | end bar | | see below for more bars | more bars (see below) | | `$` | Glissando | | `=` | tied with previous note (must come before the bar for inter-measure ties) | #### Example ([link](/nltabs/w6S0pzM)) There's a range of different bars you can use. #### Example ([link](/nltabs/8xef5TC)) ### 4.6 Multi-Voice Scores One of the interesting things about using NLTabs vs. traditional notation is that you can represent multi-voice scores more clearly. You can visually see which string plucks belong to which voices because, often, the rhythm voice has it's own movement patterns and you can see that visually on the tab. To separate out voices, you simply add a `voice:` line and name your voices appropriately. In the example below, I take the first few notes in Jingle Bells, and write a voice for the melody (named `melody` below) and one for the bass/accompaniment handed line (`accompaniment`). In the Guqin tabs, you can see the strumming pattern representing the left hand on the lower level strings (the ones further away from player on the qin, and higher up on the tabs). Attributes such as time signatures, tempo, key signatures, marks, fyhuiranges apply across voices. Other elements, notably clefs, will need to be specified for each voice. #### Example ([link](/nltabs/cn3XQhk)) To combine voices in one staff, include a `combinevoices: yes` tag. To force one voice to have steps that go up, you can add a `ly: \voiceOne` to the beginning of that voice. To force stems down, add `ly: \voiceTwo` at the beginning. (`\voiceThree` and `\voiceFour` works too) #### Example ([link](/nltabs/WGxQ3mo)) ## 5. Writing Music in JianZiPu JianZiPu lines start with `j:`. Writing in JZP follows a very similar format as writing for shorthand, except you need to specify the hui positions. For more information, see here for documentation: https://github.com/neuralfirings/JianZiPu