1.2.3 Documentation (#66)

README.md

@@ -2,9 +2,9 @@
 
 ![alphaTab](https://raw.githubusercontent.com/CoderLine/alphaTab/develop/img/banner.png)
 
-This repository contains the website and documentation of alphaTab. Head over to the main product repository to learn more. 
+This repository contains the website and documentation of alphaTab. Head over to the main product repository to learn more.
 
-Product Repository: https://github.com/CoderLine/alphaTab
-Website: http://www.alphatab.net
+Product Repository: <https://github.com/CoderLine/alphaTab>
+Website: <https://www.alphatab.net/>
 
-We are using <img alt="Docusaurus" src="https://docusaurus.io/img/docusaurus.svg" width="16" /> [Docusaurus](https://docusaurus.io//) for our the docs. 
+We are using <img alt="Docusaurus" src="https://docusaurus.io/img/docusaurus.svg" width="16" /> [Docusaurus](https://docusaurus.io/) for the docs.

docs/alphatex/bar-metadata.mdx

@@ -5,65 +5,76 @@ title: Bar Metadata
 import { AlphaTexSample } from '@site/src/components/AlphaTexSample';
 
 For bars various tags can be specified which change information like
-clefs, key signatures repeats etc. They follow the format 
-`\tag value value` just like the score metadata. Be sure not to 
+clefs, key signatures repeats etc. They follow the format
+`\tag value value` just like the score metadata. Be sure not to
 mix the score metadata and the bar metadata of the first bar.
 
 ## Time Signatures
 
-Time signatures have the format `\ts Numerator Denominator`
+Time signatures have the format `\ts Numerator Denominator`.
 
 <AlphaTexSample>{`
-\\ts 3 4 | \\ts 4 4 | \\ts 6 8       
+\\ts 3 4 | \\ts 4 4 | \\ts 6 8
 `}</AlphaTexSample>
 
 ## Repeats
 
-Repeats can be started with `\ro` and 
+Repeats can be started with `\ro` and
 be closed with `\rc Count`. Count specifies how many times
-the bar range is repeated. 
+the bar range is repeated.
 
 <AlphaTexSample>{`
-\\ro 1.3 2.3 3.3 4.3 |   
-5.3 6.3 7.3 8.3 |   
-\\rc 2 1.3 2.3 3.3 4.3 |  
-\\ro \\rc 3 1.3 2.3 3.3 4.3 |   
+\\ro 1.3 2.3 3.3 4.3 | 5.3 6.3 7.3 8.3 | \\rc 2 1.3 2.3 3.3 4.3 |
+\\ro \\rc 3 1.3 2.3 3.3 4.3
+`}</AlphaTexSample>
+
+### Alternate Endings
+
+Alternate endings in a repeat range are specified with a list of numbers:
+`\ae (Repetition Repetition...)` or just `\ae Repetition` if only one number.
+Each "Repetition" number specifies in which repetition that ending bar should be played.
+
+<AlphaTexSample>{`
+\\ro 1.3 2.3 3.3 4.3 | \\ae (1 2 3) 5.3 6.3 7.3 8.3 | \\ae 4 \\rc 4 5.3 8.3 7.3 6.3
 `}</AlphaTexSample>
 
 ## Key Signatures
 
-The key signature can be specified with `\ks Value` where the value is one 
-of the following: `Cb, Gb, Db, Ab, Eb, Bb, F, C, G, D, A, E, B, F#, C#`
-
+The key signature can be specified with `\ks Value`.
+For major keys, the value is one of `Cb, Gb, Db, Ab, Eb, Bb, F, C, G, D, A, E, B, F#, C#`.
+Their equivalent minor scale can also be used, so `Bminor` is the same as `D` etc.
+A major scale can also be explicitly written out, like `Dmajor`.
+
 <AlphaTexSample>{`
-\\ks Cb | \\ks C | \\ks C# 
+\\ks Cb | \\ks C | \\ks C# |
+\\ks Aminor | \\ks Dmajor | \\ks Bminor
 `}</AlphaTexSample>
 
 ## Clef
 
 To change the clef simply specify `\clef Clef` where Clef is one of the following
 values: `G2, Treble, F4, Bass, C3, Tenor, C4, Alto, N, Neutral`
-						   
+
 <AlphaTexSample>{`
 \\clef G2 | \\clef F4 | \\clef C3 | \\clef C4 | \\clef N |
-\\clef Treble | \\clef Bass | \\clef Tenor | \\clef Alto | \\clef Neutral |
+\\clef Treble | \\clef Bass | \\clef Tenor | \\clef Alto | \\clef Neutral
 `}</AlphaTexSample>
 
 ## Tempo
 
 To change the tempo of the score you can specify `\tempo BPM`.
-						   
+
 <AlphaTexSample>{`
 // score meta also supports \\tempo, therefore we skip the score meta with a dot
 .
-// bars
-\\tempo 30 1.3 2.3 3.3 4.3 | 
-\\tempo 80 1.3 2.3 3.3 4.3 |
+// change tempo in bars
+\\tempo 30 1.3 2.3 3.3 4.3 |
+\\tempo 80 1.3 2.3 3.3 4.3
 `}</AlphaTexSample>
 
 ## Triplet Feel
 
-To change the triplet feel of a bar specify `\tf TripletFeel`. Where `TripletFeel` is one of the following values: 
+To change the triplet feel of a bar, specify `\tf TripletFeel`, where `TripletFeel` is one of the following values:
 
 | TripletFeel       | Possible values       |
 |-------------------|-----------------------|
@@ -74,30 +85,38 @@ To change the triplet feel of a bar specify `\tf TripletFeel`. Where `TripletFee
 | Dotted 8th        | dotted-8th, d8, 4     |
 | Scottish 16th     | scottish-16th, s16, 5 |
 | Scottish 8th      | scottish-8th, s8, 6   |
-						   
+
 <AlphaTexSample>{`
-\\tf none 3.3*4 | \\tf triplet-16th 3.3*4 | \\tf triplet-8th 3.3*4 | \\tf dotted-16th 3.3*4 | \\tf dotted-8th 3.3*4 | \\tf scottish-16th 3.3*4 | \\tf scottish-8th 3.3*4 |
-\\tf no 1.1*4 | \\tf t16 1.1*4 | \\tf t8 1.1*4 | \\tf d16 1.1*4 | \\tf d8 1.1*4 | \\tf s16 1.1*4 | \\tf s8 1.1*4
+\\tf none 3.3*4 |
+\\tf triplet-16th 3.3*4 | \\tf triplet-8th 3.3*4 |
+\\tf dotted-16th 3.3*4 | \\tf dotted-8th 3.3*4 |
+\\tf scottish-16th 3.3*4 | \\tf scottish-8th 3.3*4 |
+\\tf no 1.1*4 |
+\\tf t16 1.1*4 | \\tf t8 1.1*4 |
+\\tf d16 1.1*4 | \\tf d8 1.1*4 |
+\\tf s16 1.1*4 | \\tf s8 1.1*4
 `}</AlphaTexSample>
 
 ## Anacrusis
 
-By default bars follow a strict timing defined by the time signature and tempo. Anacrusis (aka. pickup bars) do not follow this rule. 
+By default bars follow a strict timing defined by the time signature and tempo. Anacrusis (aka. pickup bars) do not follow this rule.
 The length of those bars is defined by the actual beats/notes in the bar. Bars can be flagged as anacrusis bars via the `\ac` bar meta.
-						   
+
 <AlphaTexSample>{`
 \\ks D \\ts 24 16 \\ac r.16 6.3 7.3 9.3 7.3 6.3 | r.16 5.4 7.4 9.4 7.4 5.4 6.3.4{d} 9.6.16 10.6 12.6 10.6 9.6 14.6.4{d} r.16
 `}</AlphaTexSample>
 
 ## Sections
 
-To split your song into individual sections (e.g. intro, chorus, solo etc.) you can mark a bar as a section start by using `\section` followed by the section name. If you want to also specify a marker beside the text, use the format `\section Marker Text`
+To split your song into individual sections (e.g. intro, chorus, solo etc.)
+you can mark a bar as a section start by using `\section` followed by the section name.
+If you want to also specify a marker beside the text, use the format `\section Marker Text`.
 
 <AlphaTexSample>{`
-\\section Intro // simple section 
-1.1 1.1 1.1 1.1 | 1.1 1.1 1.1 1.1 | 
+\\section Intro // simple section
+1.1 1.1 1.1 1.1 | 1.1 1.1 1.1 1.1 |
 \\section "Chorus 01" // with spaces in name
-1.1 1.1 1.1 1.1 | 
+1.1 1.1 1.1 1.1 |
 \\section S Solo // with marker and section name differently
 1.1 1.1 1.1 1.1
 `}</AlphaTexSample>

docs/alphatex/beat-effects.mdx

@@ -5,12 +5,12 @@ title: Beat Effects
 import { AlphaTexSample } from '@site/src/components/AlphaTexSample';
 
 There are various effects that can be applied to a beat. All beat
-effects are specified in braces after the beat. 
-`Beat{Effects}` Multiple effects are simply separated by spaces like `3.3 {f v}`
+effects are specified in braces after the beat: `Beat{Effects}`.
+Multiple effects are simply separated by spaces, like `3.3{f v}`.
 
 ## Simple Effects
 
-Please find the list of support effects in the example below. 
+Please find the list of supported effects in the example below.
 
 <AlphaTexSample>{`
 // fade in
@@ -39,11 +39,11 @@ Please find the list of support effects in the example below.
 3.3{gr}
 3.3
 |
-// Tuplets (supported variants: 3,5,6,7,9,10,11,12)
+// Tuplets (supported variants: 3, 5, 6, 7, 9, 10, 11, 12)
 3.3{tu 3} 3.3{tu 3} 3.3{tu 3}
 3.3{tu 5} 3.3{tu 5} 3.3{tu 5} 3.3{tu 5} 3.3{tu 5}
 |
-// tremolo picking (tp duration - where duration can be 8,16 or 32)
+// tremolo picking (tp duration - where duration can be 8, 16 or 32)
 3.3{tp 8} 3.3{tp 16} 3.3{tp 32}
 |
 // Crescendo / Decrescendo
@@ -52,7 +52,7 @@ Please find the list of support effects in the example below.
 
 ## Dynamics
 
-Dynamics are beat effects with the indicator `dy` followed by one of the supported dynamics values FFF, FF, F, MF, MP, P, PP or PPP
+Dynamics are beat effects with the indicator `dy` followed by one of the supported dynamics values FFF, FF, F, MF, MP, P, PP or PPP.
 
 <AlphaTexSample>{`
 1.1.8{dy ppp} 1.1{dy pp} 1.1{dy p} 1.1{dy mp} 1.1{dy mf} 1.1{dy f} 1.1{dy ff} 1.1{dy fff}
@@ -62,42 +62,57 @@ Dynamics are beat effects with the indicator `dy` followed by one of the support
 
 You can also specify the tuplet as part of a ranged duration. This makes writing tuplets a bit easier if there are many.
 To reset the tuplet range, a new duration range can be started. For individual notes other tuplets can be specified too.
-1 can be used to specify no tuplet while a tuplet range is active. 
+`{tu 1}` can be used to specify no tuplet while a tuplet range is active.
 
 <AlphaTexSample>{`
-:4{tu 3} 3.3 3.3 3.3 :8 3.3 3.3 3.3 3.3 | :8{tu 3} 3.3 3.3 3.3 3.3.16 3.3.16 3.3.16 3.3.2{tu 1} 3.3.16{tu 1} 3.3.4 3.3.4 3.3.4
+:4{tu 3} 3.3 3.3 3.3 :8 3.3 3.3 3.3 3.3 |
+:8{tu 3} 3.3 3.3 3.3 3.3.16 3.3.16 3.3.16 3.3.2{tu 1} 3.3.16{tu 1} 3.3.4 3.3.4 3.3.4
 `}</AlphaTexSample>
 
 ## Tremolo / Whammy Bar
 
-The tremolo/whammy bar effect is a bit more complex than the others. 
+The tremolo/whammy bar effect is a bit more complex than the others.
 You can specify a number of values which are evenly distributed over the
-time when the note is played. The values indicate the number of quarter notes
-increased or decreased on playing. `tb (value1 value2 ...)`
+time when the note is played with the format `tb (value1 value2 ...)`.
+The values indicate the number of quarter notes increased or decreased while playing.
 
 <AlphaTexSample>{`
 3.3.1{tb (0 4 0 8)} |
 3.3.1{tb (0 -4 0 -8)} |
 `}</AlphaTexSample>
 
+## Brushes / Arpeggio
+
+Brush stroke effetcs are: brush down `bd`, brush up `bu`, arpeggio down `ad`, and arpeggio up `au`.
+By default, the duration between notes is calculated based on the number of notes in the beat (the chord).
+A custom duration (in MIDI ticks) can also be specified with, for example `bd 120`.
+
+<AlphaTexSample>{`
+:2 (0.1 0.2 0.3 2.4 2.5 0.6){bd} (0.1 0.2 0.3 2.4 2.5 0.6){bu} |
+(0.1 0.2 0.3 2.4 2.5 0.6){ad} (0.1 0.2 0.3 2.4 2.5 0.6){au} |
+(0.1 0.2 0.3 2.4 2.5 0.6){bd 360} (0.1 0.2 0.3 2.4 2.5 0.6){bu 60}
+`}</AlphaTexSample>
+
 ## Chords
 
-If you want to specify chords on top of your beats this can be done via the `ch "ChordName"` effect. This will annotate on the beat the chord name.  
+If you want to specify chords on top of your beats this can be done via the `ch "ChordName"` effect.
+This will annotate the chord name above the beat.
 
 <AlphaTexSample>{`
-(1.1 3.2 5.3 3.4 1.5){ch "A#add9"} (1.1 3.2 5.3 3.4 1.5) (1.1 3.2 5.3 3.4 1.5) (1.1 3.2 5.3 3.4 1.5) |
-(4.1 6.2 6.3 6.4 4.5){ch "C#"} (4.1 6.2 6.3 6.4 4.5) (4.1 6.2 6.3 6.4 4.5) (4.1 6.2 6.3 6.4 4.5) |
-(6.1 8.2 8.3 8.4 6.5){ch "D"} (6.1 8.2 8.3 8.4 6.5) (6.1 8.2 8.3 8.4 6.5) (6.1 8.2 8.3 8.4 6.5) |
-(0.1 0.2 1.3 2.4 2.5 0.6){ch "E"} (0.1 0.2 1.3 2.4 2.5 0.6) (0.1 0.2 1.3 2.4 2.5 0.6) (0.1 0.2 1.3 2.4 2.5 0.6)
+(1.1 3.2 5.3 3.4 1.5){ch "A#add9"} (1.1 3.2 5.3 3.4 1.5)*3 |
+(4.1 6.2 6.3 6.4 4.5){ch "C#"} (4.1 6.2 6.3 6.4 4.5)*3 |
+(6.1 8.2 8.3 8.4 6.5){ch "D"} (6.1 8.2 8.3 8.4 6.5)*3 |
+(0.1 0.2 1.3 2.4 2.5 0.6){ch "E"} (0.1 0.2 1.3 2.4 2.5 0.6)*3
 `}</AlphaTexSample>
 
 <h3 id="chord-diagrams">Chord Diagrams</h3>
 
-You can also define chord diagrams for each chord. For this a global metadata `chord` can define the details for each chord. The format of this metadata is `\chord &lt;ChordName&gt; &lt;String1&gt; &lt;String2&gt;...`. For all strings a value must be defined, `x` annotates that the string is not played.   
+A global metadata tag `\chord` can define the chord diagram for each chord.
+The format is `\chord ChordName String1 String2 ...`. A value must be defined for all strings. `x` annotates that the string is not played.
 Additionally there are 4 properties which adjust the chord details: 
 
-* `FirstFret Number` - shifts the first fret shown in the diagram higher
-* `Baree Fret1 Fret2..` - defines on which frets a barré should be played (joins the dots to a bar)
+* `FirstFret Number` - shifts the first fret shown in the diagram higher.
+* `Barre Fret1 Fret2 ...` - defines on which frets a barré should be played (visually joins the dots to a bar).
 * `ShowDiagram True/False` - enables/disables whether the chord diagram should be shown.
 * `ShowName True/False` - enables/disables whether the chord name is shown above the diagram.
 

docs/alphatex/introduction.mdx

@@ -6,26 +6,26 @@ import { AlphaTexSample } from '@site/src/components/AlphaTexSample';
 
 In this section you find all details about how to write music notation using AlphaTex.
 AlphaTex is a text format for writing music notation for AlphaTab. AlphaTex loading
-can be enabled by specifying `data-tex="true"` on the container elmement. 
-AlphaTab will load the tex code from the element contents and parse it. 
+can be enabled by specifying `data-tex="true"` on the container elmement.
+AlphaTab will load the tex code from the element contents and parse it.
 AlphaTex supports most of the features alphaTab supports overall. If you find anything
 missing you would like to see, feel free to [initiate a Discussion on GitHub](https://github.com/CoderLine/alphaTab/discussions/new) so we can find a good solution together.
 
 ## Showcase
 
-Here is an example score fully rendered using alphaTex. 
+Here is an example score fully rendered using alphaTex.
 
 <AlphaTexSample>{`
 \\title "Canon Rock"
 \\subtitle "JerryC"
 \\tempo 90
 .
-:2 19.2{v f} 17.2{v f} | 
-15.2{v f} 14.2{v f}| 
-12.2{v f} 10.2{v f}| 
+:2 19.2{v f} 17.2{v f} |
+15.2{v f} 14.2{v f}|
+12.2{v f} 10.2{v f}|
 12.2{v f} 14.2{v f}.4 :8 15.2 17.2 |
-14.1.2 :8 17.2 15.1 14.1{h} 17.2 | 
+14.1.2 :8 17.2 15.1 14.1{h} 17.2 |
 15.2{v d}.4 :16 17.2{h} 15.2 :8 14.2 14.1 17.1{b(0 4 4 0)}.4 |
-15.1.8 :16 14.1{tu 3} 15.1{tu 3} 14.1{tu 3} :8 17.2 15.1 14.1 :16 12.1{tu 3} 14.1{tu 3} 12.1{tu 3} :8 15.2 14.2 | 
+15.1.8 :16 14.1{tu 3} 15.1{tu 3} 14.1{tu 3} :8 17.2 15.1 14.1 :16 12.1{tu 3} 14.1{tu 3} 12.1{tu 3} :8 15.2 14.2 |
 12.2 14.3 12.3 15.2 :32 14.2{h} 15.2{h} 14.2{h} 15.2{h}14.2{h} 15.2{h}14.2{h} 15.2{h}14.2{h} 15.2{h}14.2{h} 15.2{h}14.2{h} 15.2{h}14.2{h} 15.2{h}
 `}</AlphaTexSample>

docs/alphatex/metadata.mdx

@@ -6,7 +6,7 @@ import { AlphaTexSample } from '@site/src/components/AlphaTexSample';
 
 Metadata is specified using `\tagname value value` at the beginning of the score. 
 It can be used to specify global information like title, tempo or track tuning.
-Metadata is optional, but if specified, it must be followed by a dot do indicate the end
+Metadata is optional, but if specified, it must be followed by a dot to indicate the end
 of the metadata. 
 
 Some of the metadata tags can also be specified when starting a new staff or track. Please refer to the [Tracks and Staves](/docs/alphatex/tracks-staves) or details on how to start new tracks and staves. 
@@ -39,7 +39,7 @@ Some of the metadata tags can also be specified when starting a new staff or tra
 ## Instrument
 As indicated above the instrument can be changed via the `\instrument` metadata. 
 Refer to the table below for all possible values and names. The list represents the general midi instrument list.
-You can either leave out the spaces or put the names into quotes e.g. `AcousticBass` vs `"Acoustic Bass"`
+You can either leave out the spaces or put the names into quotes e.g. `AcousticBass` vs `"Acoustic Bass"`.
 
 export function GeneralMidiList() {
     const items = [
@@ -198,13 +198,13 @@ export function GeneralMidiList() {
 
 ## Tuning
 
-The tuning of the instrument is defined by `\tuning` tag. For stringed instruments like the Guitar
-each tuning value defines one string. The format of the tuning value is `{note}{octave}` 
-`{note}` is one value of the following values in the given order C, C# or Db, D, D# or Eb, E, F, F# or Gb, G, G# or Ab, A, A# or Bb, B. 
-`{octave}` is just a number defining the octvate. 
+The tuning of the instrument is defined by the `\tuning` tag. For stringed instruments like the Guitar,
+each tuning value defines one string. The format of the tuning value is `{note}{octave}`.
+`{note}` is one value of the following values in the given order: C, C# or Db, D, D# or Eb, E, F, F# or Gb, G, G# or Ab, A, A# or Bb, B.
+`{octave}` is a number defining the octvate.
 
-A standard guitar tuning would be `\tuning E4 B3 G3 D3 A2 E2`
+For example, a standard guitar tuning is `\tuning E4 B3 G3 D3 A2 E2`. A 5 string bass would be `\tuning G2 D2 A1 E1 B0`.
 
-For non-stringed instruments one of the following values can be used: `piano`, `none` or `voice` depending on preference.
+For non-stringed instruments, the values `piano`, `none` or `voice` can be used depending on preference.
 
-If `\instrument` is specified without `\tuning` alphaTab will try to make a guess and apply the right default tuning. 
+If `\instrument` is specified without `\tuning`, alphaTab will try to make a guess and apply the right default tuning.