diff --git a/.github/workflows/deploy-develop.yml b/.github/workflows/deploy-develop.yml index fd01b8e..8975248 100644 --- a/.github/workflows/deploy-develop.yml +++ b/.github/workflows/deploy-develop.yml @@ -19,6 +19,7 @@ jobs: - run: npm install - run: npm install @coderline/alphatab@alpha - run: npm install -D @coderline/alphatab-webpack@alpha + - run: npm install -D @coderline/alphatab-language-server@alpha - run: npm run generate-alphatabdoc - run: npm run build - name: Package Zip diff --git a/docs/alphatex/_bar-metadata.mdx b/docs/alphatex/_bar-metadata.mdx new file mode 100644 index 0000000..9d2d3d0 --- /dev/null +++ b/docs/alphatex/_bar-metadata.mdx @@ -0,0 +1,736 @@ +import { AlphaTexSample } from '@site/src/components/AlphaTexSample'; +import { ParameterValuesTable } from '@site/src/components/ParameterValuesTable'; + +## `\ts` + +```plain title="Syntax" +// [1]: Specifies a common (4/4) time signature using the special C symbol +\ts common +// [2]: +\ts (numerator denominator) +``` + +**Description:** Defines the time signature for this and subsequent bars. + +AlphaTab does not yet support polytempo notation where instruments might use different time signatures. Therefore be sure to only specify the timesignatures once as part of the first track/staff or ensure they are consistent across the whole document. + + +**Parameters:** + +| Overload | Name | Description | Type | Required | +|----------|------|-------------|------|----------| +| `[1]` | `common` | Specifies a common (4/4) time signature using the special C symbol | `common` | yes | +| `[2]` | `numerator` | The time signature numerator | `Number` | yes | +| `[2]` | `denominator` | The time signature denominator | `Number` | yes | + +**Parameter Values:** + +Following parameters have value limitations + +| Overload | Name | Values | +|----------|------|--------| +| `[1]` | `common` | | + +**Example:** + +{` +\\ts 3 4 | \\ts 4 4 | \\ts 6 8 | \\ts common + +`} + +## `\ro` + +```plain title="Syntax" +\ro () +``` + +**Description:** Start a repeat + +**Example:** + +{` +\\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 + +`} + +## `\rc` + +```plain title="Syntax" +\rc repeats +``` + +**Description:** Marks the end of a repeat. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `repeats` | The number of repeats which should be played | `Number` | yes | + +**Example:** + +{` +\\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 + +`} + +## `\ae` + +```plain title="Syntax" +\ae (ending) +``` + +**Description:** Specifies on which repeats a bar should be played (to build alternate endings). + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `ending` | The repeats on which the bar should be played | `Number[]` | yes | + +**Example:** + +{` +\\ro 1.3 2.3 3.3 4.3 | \\ae (1 2 3) 5.3 6.3 7.3 8.3 | \\ae 4 c 4 5.3 8.3 7.3 6.3 + +`} + +## `\ks` + +```plain title="Syntax" +\ks key +``` + +**Description:** Specifies the key signature for this and subsequent bars. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `key` | The key signature | `Ident` | yes | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `key` | | + +**Example:** + +{` +\\ks Cb | \\ks C | \\ks C# | +\\ks Aminor | \\ks Dmajor | \\ks Bminor + +`} + +## `\clef` + +```plain title="Syntax" +\clef clef +``` + +**Description:** Changes the clef for this and subsequent bars. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `clef` | The clef | `Ident\|Number` | yes | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `clef` | | + +**Example:** + +{` +\\clef G2 | \\clef F4 | \\clef C3 | \\clef C4 | \\clef N | +\\clef Treble | \\clef Bass | \\clef Tenor | \\clef Alto | \\clef Neutral | + +`} + +## `\ottava` + +```plain title="Syntax" +\ottava ottava +``` + +**Description:** Changes the clef ottave for this and subsequent bars. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `ottava` | The clef ottava | `Ident` | yes | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `ottava` | | + +**Example:** + +{` +\\clef F4 \\ottava 15ma | | \\ottava regular | | \\clef C3 \\ottava 8vb | | + +`} + +## `\tempo` + +```plain title="Syntax" +// [1]: +\tempo (tempo label) +// [2]: +\tempo (tempo label position hide) +``` + +**Description:** Adds a tempo change to the bar. + +A bar can have multiple tempo changes. They can either be relatively positioned using this metadata tag or applied via the `tempo` property as beat effect. + +Tempo changes affect the whole song and not only an individual track. To avoid unexpected side effects, we recomment to specify the tempo changes only once on the first track/staff. + + +**Parameters:** + +| Overload | Name | Description | Type | Required | +|----------|------|-------------|------|----------| +| `[1]` | `tempo` | The new tempo in BPM | `Number` | yes | +| `[1]` | `label` | A textual label for the tempo | `String` | no `""` | +| `[2]` | `tempo` | The new tempo in BPM | `Number` | yes | +| `[2]` | `label` | A textual label for the tempo | `String` | yes `""` | +| `[2]` | `position` | A relative (ratio) position where within the bar the tempo change should happen | `Number` | no `0` | +| `[2]` | `hide` | If specified the tempo change is not visually shown | `hide` | no | + +**Parameter Values:** + +Following parameters have value limitations + +| Overload | Name | Values | +|----------|------|--------| +| `[2]` | `hide` | | + +**Example:** + +{` +\\tempo 30 +C4 D4 E4 F4 | +\\tempo (120 "Moderate") +\\tempo (60 "" 0.5 hide) +C4 D4 E4 F4 | + +`} + +## `\tf` + +```plain title="Syntax" +\tf tripletFeel +``` + +**Description:** Changes the triplet feel (aka. swing) play style. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `tripletFeel` | The triplet feel style | `Ident\|Number` | yes | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `tripletFeel` | | + +**Example:** + +{` +\\tf none 3.3*4 | +\\tf triplet16th 3.3*4 | \\tf triplet8th 3.3*4 | +\\tf dotted16th 3.3*4 | \\tf dotted8th 3.3*4 | +\\tf scottish16th 3.3*4 | \\tf scottish8th 3.3*4 | + +`} + +## `\ac` + +```plain title="Syntax" +\ac () +``` + +**Description:** Marks the bar as an anacrusis (pick-up) bar. + +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. + + +**Example:** + +{` +\\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 + +`} + +## `\section` + +```plain title="Syntax" +// [1]: +\section text +// [2]: +\section (marker text) +``` + +**Description:** Starts a new section + +**Parameters:** + +| Overload | Name | Description | Type | Required | +|----------|------|-------------|------|----------| +| `[1]` | `text` | The text/description of the new section | `String` | yes | +| `[2]` | `marker` | The marker for the section, typically a single letter | `String` | yes | +| `[2]` | `text` | The text/description of the new section | `String` | yes | + +**Example:** + +{` +\\section "Intro" // simple section +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 + +`} + +## `\jump` + +```plain title="Syntax" +\jump direction +``` + +**Description:** Adds a direction/jump instruction to the bar. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `direction` | The direction to add | `Ident` | yes | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `direction` | | + +**Example:** + +{` +\\ro \\rc 2 3.3*4 | + 3.3*4 | + \\jump Segno 3.3*4 | + \\ro c 2 3.3*4 | + \\jump DaCoda 3.3*4 | + 3.3*4 | 3.3*4 + \\jump DalSegnoAlCoda 3.3*4 | + 3.3*4 | + \\jump Coda 3.3*4 | + 3.3*4 | + 3.3*4 + +`} + +## `\ft` + +```plain title="Syntax" +\ft () +``` + +**Description:** Marks the bar as a free-time bar where players are free to vary the timing. + + +**Example:** + +{` +:2 +C4*2 | +\\ft C4*2 | +\\ft C4*2 | +C4*2 | + +`} + +## `\simile` + +```plain title="Syntax" +\simile mark +``` + +**Description:** Adds a simile mark to the bar indicating that the content of the last, or previous two bars should be repeated. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `mark` | The mark to add | `none\|simple\|firstOfDouble\|secondOfDouble` | yes | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `mark` | | + +**Example:** + +{` +3.3*4 | \\simile simple | 3.3*4 | 4.3*4 | \\simile firstofdouble | \\simile secondofdouble + +`} + +## `\barlineLeft` + +```plain title="Syntax" +\barlineLeft style +``` + +**Description:** Adjusts the lines which will be shown left on the bar. + +For some special notation needs, the default bar line can be adjusted on every bar. The bar line styles are aligned with the ones from [MusicXML](https://www.w3.org/2021/06/musicxml40/musicxml-reference/data-types/bar-style/). + +alphaTab attempts to reuse lines on overlapping styles across bars. + + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `style` | The line style to use | `Ident` | yes | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `style` | | + +**Example:** + +{` +\\instrument piano +\\track "Overlapping" + \\staff + \\barlineleft dashed + \\barlineright dotted + | + \\barlineleft heavyheavy + \\barlineright heavyheavy + + \\staff + \\barlineleft lightlight + \\barlineright lightheavy + | + \\barlineleft heavylight + \\barlineright dashed +\\track "All Styles" + \\staff + \\barlineright dashed | + \\barlineright dotted | + \\barlineright heavy | + \\barlineright heavyHeavy | + \\barlineright heavyLight | + \\barlineright lightHeavy | + \\barlineright lightlight | + \\barlineright none | + \\barlineright regular | + \\barlineright short | + \\barlineright tick | + +`} + +## `\barlineRight` + +```plain title="Syntax" +\barlineRight style +``` + +**Description:** Adjusts the lines which will be shown right on the bar. + +For some special notation needs, the default bar line can be adjusted on every bar. The bar line styles are aligned with the ones from [MusicXML](https://www.w3.org/2021/06/musicxml40/musicxml-reference/data-types/bar-style/). + +alphaTab attempts to reuse lines on overlapping styles across bars. + + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `style` | The line style to use | `Ident` | yes | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `style` | | + +**Example:** + +{` +\\instrument piano +\\track "Overlapping" + \\staff + \\barlineleft dashed + \\barlineright dotted + | + \\barlineleft heavyheavy + \\barlineright heavyheavy + + \\staff + \\barlineleft lightlight + \\barlineright lightheavy + | + \\barlineleft heavylight + \\barlineright dashed +\\track "All Styles" + \\staff + \\barlineright dashed | + \\barlineright dotted | + \\barlineright heavy | + \\barlineright heavyHeavy | + \\barlineright heavyLight | + \\barlineright lightHeavy | + \\barlineright lightlight | + \\barlineright none | + \\barlineright regular | + \\barlineright short | + \\barlineright tick | + +`} + +## `\scale` + +```plain title="Syntax" +\scale scale +``` + +**Description:** Adjusts the relative scale of the bar when using `systemsLayoutMode: 'UseModelLayout'` with the page layout. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `scale` | The scale of the bar within the system | `Number` | yes | + +**Example:** + +{` +\\track { defaultSystemsLayout 3 } + \\scale 0.25 :1 c4 | \\scale 0.5 c4 | \\scale 0.25 c4 | + \\scale 0.5 c4 | \\scale 2 c4 | \\scale 0.5 c4 | + c4 | c4 + +`} + +## `\width` + +```plain title="Syntax" +\width width +``` + +**Description:** Adjusts the absolute of the bar when using `systemsLayoutMode: 'UseModelLayout'` with the horizontal layout. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `width` | The absolute width of the bar | `Number` | yes | + +**Example:** + +{` +\\track + \\width 100 :1 c4 | \\width 300 c4 | \\width 350 c4 + +`} + +## `\sync` + +```plain title="Syntax" +\sync (barIndex occurence millisecondOffset ratioPosition) +``` + +**Description:** Adds a new sync point for synchronizing the music sheet with an external media source like a backing track or video player. + +alphaTex support specifying sync points for the [synchronization with external media](/docs/guides/audio-video-sync). + +It is recommended to add the sync points at the very end of the song but it is also possible to define them inbetween. + +The `barIndex`, `occurence`, `ratioPosition` parameters define the absolute position within the music sheet. The millisecondOffset defines the absolute position within the external media. + +With this information known, alphaTab can synchronize the external media with the music sheet. + + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `barIndex` | The index of the bar being synced | `Number` | yes | +| `occurence` | The occurence of the bar for which this sync point applies (on repeats) | `Number` | yes | +| `millisecondOffset` | The absolute millisecond offset within the external media | `Number` | yes | +| `ratioPosition` | The relative position within the bar where the synchronization happens | `Number` | no `0` | + +**Example:** + +import { AlphaTexSyncPointSample } from '@site/src/components/AlphaTexSyncPointSample'; + + +## `\accidentals` + +```plain title="Syntax" +\accidentals mode +``` + +**Description:** Changes the mode how alphaTab should treat accidentals when writing pitched notes. + +alphaTab can use the accidentals as specified in alphaTex, or apply accidentals automatically based on the note pitch. + + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `mode` | The mode which should be active | `auto\|explicit` | yes | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `mode` | | + +**Example:** + +{` +\\accidentals explicit +C#4 C4 Eb4 Ax4 | +\\accidentals auto +C#4 C4 Eb4 Ax4 | + +`} + +## `\spd` + +```plain title="Syntax" +\spd position +``` + +**Description:** Specifies how the sustain petal should be pressed down (`spd`), held (`sph`) or lifted up (`spu`). + +This tag allows specifying the sustain pedal relative to the bar. The sustain pedal can also be applied via beat properties. + + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `position` | The relative position within the bar for the marker (0-1) | `Number` | yes | + +**Example:** + +{` +\\spd 0 +\\spu 0.25 +\\spd 0.5 +\\sph 0.75 +\\spu 1 +:8 C4 * 8 + +`} + +## `\sph` + +```plain title="Syntax" +\sph position +``` + +**Description:** Specifies how the sustain petal should be pressed down (`spd`), held (`sph`) or lifted up (`spu`). + +This tag allows specifying the sustain pedal relative to the bar. The sustain pedal can also be applied via beat properties. + + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `position` | The relative position within the bar for the marker (0-1) | `Number` | yes | + +**Example:** + +{` +\\spd 0 +\\spu 0.25 +\\spd 0.5 +\\sph 0.75 +\\spu 1 +:8 C4 * 8 + +`} + +## `\spu` + +```plain title="Syntax" +\spu position +``` + +**Description:** Specifies how the sustain petal should be pressed down (`spd`), held (`sph`) or lifted up (`spu`). + +This tag allows specifying the sustain pedal relative to the bar. The sustain pedal can also be applied via beat properties. + + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `position` | The relative position within the bar for the marker (0-1) | `Number` | yes | + +**Example:** + +{` +\\spd 0 +\\spu 0.25 +\\spd 0.5 +\\sph 0.75 +\\spu 1 +:8 C4 * 8 + +`} + +## `\db` + +```plain title="Syntax" +\db () +``` + +**Description:** Mark a double-bar + +**Example:** + +{` + +`} + diff --git a/docs/alphatex/_beat-properties.mdx b/docs/alphatex/_beat-properties.mdx new file mode 100644 index 0000000..8b71cf2 --- /dev/null +++ b/docs/alphatex/_beat-properties.mdx @@ -0,0 +1,1131 @@ +import { AlphaTexSample } from '@site/src/components/AlphaTexSample'; +import { ParameterValuesTable } from '@site/src/components/ParameterValuesTable'; + +## `f` + +```plain title="Syntax" +f () +``` + +**Description:** Adds a fade-in effect to the beat. Applies to all notes. + +**Example:** + +{` +(0.1 2.2 2.3 2.4 0.5).2 { f } + +`} + +## `fo` + +```plain title="Syntax" +fo () +``` + +**Description:** Adds a fade-out effect to the beat. Applies to all notes. + +**Example:** + +{` +(0.1 2.2 2.3 2.4 0.5).1 { fo } + +`} + +## `vs` + +```plain title="Syntax" +vs () +``` + +**Description:** Adds a volume-swell effect to the beat. Applies to all notes. + +**Example:** + +{` +(0.1 2.2 2.3 2.4 0.5).1 { vs } + +`} + +## `v` + +```plain title="Syntax" +v () +``` + +**Description:** Adds a slight vibrato effect to the beat. Applies to all notes. + +**Example:** + +{` +(0.1 2.2 2.3 2.4 0.5).1 { v } + +`} + +## `vw` + +```plain title="Syntax" +vw () +``` + +**Description:** Adds a wide vibrato effect to the beat. Applies to all notes. + +**Example:** + +{` +(0.1 2.2 2.3 2.4 0.5).1 { vw } + +`} + +## `s` + +```plain title="Syntax" +s () +``` + +**Description:** Adds a bass slap annotation to the beat. + +**Example:** + +{` +\\track {instrument "Electric Bass Finger"} +(3 4) 3.4.8 {s} (5.1 5.2).4 {p} 3.4.8 {s} (5.1 5.2).4 {p} + +`} + +## `p` + +```plain title="Syntax" +p () +``` + +**Description:** Adds a bass pop annotation to the beat. + +**Example:** + +{` +\\track {instrument "Electric Bass Finger"} +(3 4) 3.4.8 {s} (5.1 5.2).4 {p} 3.4.8 {s} (5.1 5.2).4 {p} + +`} + +## `tt` + +```plain title="Syntax" +tt () +``` + +**Description:** Adds a guitar or bass tapping annotation to the beat. + +**Example:** + +{` +\\track {instrument "Electric Bass Finger"} +:8 {tu 3} +18.1 {tt h} 10.1 {h} 14.1 +18.1 {tt h} 10.1 {h} 14.1 +18.1 {tt h} 10.1 {h} 14.1 +18.1 {tt h} 10.1 {h} 14.1 + +`} + +## `d` + +```plain title="Syntax" +d () +``` + +**Description:** Marks the beat with a single augmentation dot. + +**Example:** + +{` +(0.1 2.2 2.3 2.4 0.5).1 { d } + +`} + +## `dd` + +```plain title="Syntax" +dd () +``` + +**Description:** Marks the beat with a double augmentation dot. + +**Example:** + +{` +(0.1 2.2 2.3 2.4 0.5).1 { dd } + +`} + +## `su` + +```plain title="Syntax" +su () +``` + +**Description:** Adds an upwards pick-stroke annotation to the beat. + +**Example:** + +{` +0.1 { su } + +`} + +## `sd` + +```plain title="Syntax" +sd () +``` + +**Description:** Adds an downwards pick-stroke annotation to the beat. + +**Example:** + +{` +0.1 { sd } + +`} + +## `cre` + +```plain title="Syntax" +cre () +``` + +**Description:** Adds a crescendo effect to the beat. + +**Example:** + +{` +3.3 { cre } -.3 { cre } + +`} + +## `dec` + +```plain title="Syntax" +dec () +``` + +**Description:** Adds a decrescendo (diminuendo) effect to the beat. + +**Example:** + +{` +3.3 { dec } -.3 { dec } + +`} + +## `spd` + +```plain title="Syntax" +spd () +``` + +**Description:** Add a sustain pedal down-press to the beat. + +**Example:** + +{` +C4 {spd} C4 {sph} C4 {sph} C4 {spu} | +C4 {spd} C4 {sph} C4 {sph} C4 {spe} + +`} + +## `sph` + +```plain title="Syntax" +sph () +``` + +**Description:** Add a sustain pedal hold to the beat. + +**Example:** + +{` +C4 {spd} C4 {sph} C4 {sph} C4 {spu} | +C4 {spd} C4 {sph} C4 {sph} C4 {spe} + +`} + +## `spu` + +```plain title="Syntax" +spu () +``` + +**Description:** Add a sustain pedal up (release) to the beat. + +**Example:** + +{` +C4 {spd} C4 {sph} C4 {sph} C4 {spu} | +C4 {spd} C4 {sph} C4 {sph} C4 {spe} + +`} + +## `spe` + +```plain title="Syntax" +spe () +``` + +**Description:** Add a sustain pedal up (release) to the end of the beat. + +**Example:** + +{` +C4 {spd} C4 {sph} C4 {sph} C4 {spu} | +C4 {spd} C4 {sph} C4 {sph} C4 {spe} + +`} + +## `slashed` + +```plain title="Syntax" +slashed () +``` + +**Description:** Marks the beat to be displayed with slash notation. + +**Example:** + +{` +(0.1 2.2 2.3 2.4 0.5).2 (0.1 2.2 2.3 2.4 0.5).2 { slashed } + +`} + +## `ds` + +```plain title="Syntax" +ds () +``` + +**Description:** Marks the beat to be a dead-slap beat. + +As no notes should be on such a beat, simply use () to indicate the empty beat which is not a rest. + + +**Example:** + +{` +().4 {ds} ().4 {ds} + +`} + +## `glpf` + +```plain title="Syntax" +glpf () +``` + +**Description:** Adds a golpe finger-tap effect to the beat. + +**Example:** + +{` +3.3{glpf} 3.3{glpt} + +`} + +## `glpt` + +```plain title="Syntax" +glpt () +``` + +**Description:** Adds a golpe thumb-tap effect to the beat. + +**Example:** + +{` +3.3{glpf} 3.3{glpt} + +`} + +## `waho` + +```plain title="Syntax" +waho () +``` + +**Description:** Adds a Wah-pedal opening effect to the beat. + +**Example:** + +{` +3.3 3.3{waho} 3.3 3.3 {wahc} + +`} + +## `wahc` + +```plain title="Syntax" +wahc () +``` + +**Description:** Adds a Wah-pedal close effect to the beat. + +**Example:** + +{` +3.3 3.3{waho} 3.3 3.3 {wahc} + +`} + +## `legatoOrigin` + +```plain title="Syntax" +legatoOrigin () +``` + +**Description:** Adds a legato from this beat to the next one. + +**Example:** + +{` +3.3.4{ legatoOrigin } 10.3.4 + +`} + +## `timer` + +```plain title="Syntax" +timer () +``` + +**Description:** Adds a timestamp marker to the beat. + +Timers are showing the exact timestamp when a beat is played the first time (respecting aspects like repeats). + + +**Example:** + +{` +\\tempo 120 +3.3.4 { timer } 3.3.4*3 | +\\ro 3.3.4 { timer } 3.3.4*3 | +3.3.4 { timer } 3.3.4*3 | +\\jump fine 3.3.4 { timer } 3.3.4*3 | +\\ae (1) 3.3.4 { timer } 3.3.4*3 | +\\ae (2 3) \\rc 3 3.3.4 { timer } 3.3.4*3 | +3.3.4 { timer } 3.3.4*3 | +\\jump DaCapoAlFine 3.3.4 { timer } 3.3.4*3 | +3.3.4 { timer } 3.3.4*3 + +`} + +## `tu` + +```plain title="Syntax" +// [1]: +tu simple +// [2]: +tu (numerator denominator) +``` + +**Description:** Adds a tuplet to the beat duration. + +There are some built-in simple tuplet variants or you can specify the exact division. + + +**Parameters:** + +| Overload | Name | Description | Type | Required | +|----------|------|-------------|------|----------| +| `[1]` | `simple` | The simple tuplet | `Number` | yes | +| `[2]` | `numerator` | The tuplet numerator | `Number` | yes | +| `[2]` | `denominator` | The tuplet denominator | `Number` | yes | + +**Parameter Values:** + +Following parameters have value limitations + +| Overload | Name | Values | +|----------|------|--------| +| `[1]` | `simple` | | + +**Example:** + +{` +C4 {tu 3} * 3 | +C4 {tu 5} * 5 | +C4 {tu 5 2} * 5 + +`} + +## `txt` + +```plain title="Syntax" +txt text +``` + +**Description:** Adds a text annotation to the beat. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `text` | The text to show above the beat | `String` | yes | + +**Example:** + +{` +C4 {txt "This is a C4 Note"} + +`} + +## `lyrics` + +```plain title="Syntax" +// [1]: +lyrics text +// [2]: +lyrics (line text) +``` + +**Description:** Adds a lyric text to the beat. + +This is an alternative way of applying the exact lyrics to beats instead of using the `\lyrics` metadata where a special syntax is used to spread the text across beats. + + +**Parameters:** + +| Overload | Name | Description | Type | Required | +|----------|------|-------------|------|----------| +| `[1]` | `text` | The lyrics to show | `String` | yes | +| `[2]` | `line` | The line number (e.g. for multiple verses) | `Number` | yes | +| `[2]` | `text` | The lyrics to show | `String` | yes | + +**Example:** + +{` +C4 {lyrics "Do"} +D4 {lyrics "Re"} +E4 {lyrics "Mi"} +F4 {lyrics "Fa"} | +G4 {lyrics 0 "So" lyrics 1 "G"} +A4 {lyrics 0 "La" lyrics 1 "A"} +B4 {lyrics 0 "Ti" lyrics 1 "B"} +r + +`} + +## `tb` + +```plain title="Syntax" +// [1]: +tb (values) +// [2]: +tb (type values) +// [3]: +tb (style values) +// [4]: +tb (type style values) +``` + +**Description:** Adds a whammy bar (aka. tremolo bar) effect to the beat. + +* The `tb` variant automatically spreads the values across the duration of the beat. +* The `tbe` (exact) variant allows specifying exactly at which offset a value is placed. + +It is recommended to rely on the auto-detection of the type and only specify the type explicitly if something is wrong. + + +**Parameters:** + +| Overload | Name | Description | Type | Required | +|----------|------|-------------|------|----------| +| `[1]` | `values` | The values of the whammy in quarter-tones relative to the original note, decimals supported | `Number[]` | no | +| `[2]` | `type` | The type of whammy (affects the display). | `Ident` | yes | +| `[2]` | `values` | The values of the whammy in quarter-tones relative to the original note, decimals supported | `Number[]` | no | +| `[3]` | `style` | The style of the whammy play style. | `default\|gradual\|fast` | yes | +| `[3]` | `values` | The values of the whammy in quarter-tones relative to the original note, decimals supported | `Number[]` | no | +| `[4]` | `type` | The type of whammy (affects the display). | `Ident` | yes | +| `[4]` | `style` | The style of the whammy play style. | `default\|gradual\|fast` | yes | +| `[4]` | `values` | The values of the whammy in quarter-tones relative to the original note, decimals supported | `Number[]` | no | + +**Parameter Values:** + +Following parameters have value limitations + +| Overload | Name | Values | +|----------|------|--------| +| `[2]` | `type` | B->A whammy pattern."],["hold","Holding whammys (on tied notes)."],["predive","Press/pull before playing the note and then kept"],["prediveDive","Whammy bar is pressed/pulled before playing the note and then further pressed/released"]]} /> | +| `[3]` | `style` | | +| `[4]` | `type` | B->A whammy pattern."],["hold","Holding whammys (on tied notes)."],["predive","Press/pull before playing the note and then kept"],["prediveDive","Whammy bar is pressed/pulled before playing the note and then further pressed/released"]]} /> | +| `[4]` | `style` | | + +**Example:** + +{` +3.3.1{tb (0 4 0 8)} | r | +3.3.1{tb (0 -4 0 -8)} | r | +3.3.1{tbe (0 0 5 4 30 8 60 0)} + +`} + +## `tbe` + +```plain title="Syntax" +// [1]: +tbe (valuesAndOffsets) +// [2]: +tbe (type valuesAndOffsets) +// [3]: +tbe (style valuesAndOffsets) +// [4]: +tbe (type style valuesAndOffsets) +``` + +**Description:** Adds a whammy bar (aka. tremolo bar) effect to the beat. + +* The `tb` variant automatically spreads the values across the duration of the beat. +* The `tbe` (exact) variant allows specifying exactly at which offset a value is placed. + +It is recommended to rely on the auto-detection of the type and only specify the type explicitly if something is wrong. + + +**Parameters:** + +| Overload | Name | Description | Type | Required | +|----------|------|-------------|------|----------| +| `[1]` | `valuesAndOffsets` | The offset at which the value becomes valid in range of 0-60 and
The value of the whammy in quarter-tones relative to the original note, decimals supported.
The offset and value are actually two parameters:
`3.3.1{tbe (0 0 5 4 30 8 60 0)}`
| `Number[]` | no | +| `[2]` | `type` | The type of whammy (affects the display). | `Ident` | yes | +| `[2]` | `valuesAndOffsets` | The offset at which the value becomes valid in range of 0-60 and
The value of the whammy in quarter-tones relative to the original note, decimals supported.
The offset and value are actually two parameters:
`3.3.1{tbe (0 0 5 4 30 8 60 0)}`
| `Number[]` | no | +| `[3]` | `style` | The style of the whammy. | `default\|gradual\|fast` | yes | +| `[3]` | `valuesAndOffsets` | The offset at which the value becomes valid in range of 0-60 and
The value of the whammy in quarter-tones relative to the original note, decimals supported.
The offset and value are actually two parameters:
`3.3.1{tbe (0 0 5 4 30 8 60 0)}`
| `Number[]` | no | +| `[4]` | `type` | The type of whammy (affects the display). | `Ident` | yes | +| `[4]` | `style` | The style of the whammy. | `default\|gradual\|fast` | yes | +| `[4]` | `valuesAndOffsets` | The offset at which the value becomes valid in range of 0-60 and
The value of the whammy in quarter-tones relative to the original note, decimals supported.
The offset and value are actually two parameters:
`3.3.1{tbe (0 0 5 4 30 8 60 0)}`
| `Number[]` | no | + +**Parameter Values:** + +Following parameters have value limitations + +| Overload | Name | Values | +|----------|------|--------| +| `[2]` | `type` | B->A whammy pattern."],["hold","Holding whammys (on tied notes)."],["predive","Press/pull before playing the note and then kept"],["prediveDive","Whammy bar is pressed/pulled before playing the note and then further pressed/released"]]} /> | +| `[3]` | `style` | | +| `[4]` | `type` | B->A whammy pattern."],["hold","Holding whammys (on tied notes)."],["predive","Press/pull before playing the note and then kept"],["prediveDive","Whammy bar is pressed/pulled before playing the note and then further pressed/released"]]} /> | +| `[4]` | `style` | | + +**Example:** + +{` +3.3.1{tb (0 4 0 8)} | r | +3.3.1{tb (0 -4 0 -8)} | r | +3.3.1{tbe (0 0 5 4 30 8 60 0)} + +`} + +## `bu` + +```plain title="Syntax" +bu duration +``` + +**Description:** Adds a brush stroke effect to the beat. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `duration` | A custom duration of the stroke speed in MIDI ticks | `Number` | no | + +**Example:** + +{` +: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){bd 360} (0.1 0.2 0.3 2.4 2.5 0.6){bu 60} + +`} + +## `bd` + +```plain title="Syntax" +bd duration +``` + +**Description:** Adds a brush stroke effect to the beat. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `duration` | A custom duration of the stroke speed in MIDI ticks | `Number` | no | + +**Example:** + +{` +: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){bd 360} (0.1 0.2 0.3 2.4 2.5 0.6){bu 60} + +`} + +## `au` + +```plain title="Syntax" +au duration +``` + +**Description:** Adds an arpeggio effect to the beat. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `duration` | A custom duration of the stroke speed in MIDI ticks | `Number` | no | + +**Example:** + +{` +(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} | + +`} + +## `ad` + +```plain title="Syntax" +ad duration +``` + +**Description:** Adds an arpeggio effect to the beat. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `duration` | A custom duration of the stroke speed in MIDI ticks | `Number` | no | + +**Example:** + +{` +(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} | + +`} + +## `ch` + +```plain title="Syntax" +ch chordName +``` + +**Description:** Adds a chord annotation to the beat. + +If the staff has a definition for this chord it will be shown in the chord diagram list to indicate its usage. The beat still has to define the notes separately. + + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `chordName` | The name of the chord | `String` | yes | + +**Example:** + +{` +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} + +`} + +## `gr` + +```plain title="Syntax" +gr type +``` + +**Description:** Marks the beat as a grace beat holding grace notes. + + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `type` | The type of grace notes | `Ident` | no `bb` | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `type` | | + +**Example:** + +{` +C5 +D5 {gr} C5 +C5 +D5 {gr} C5 + | + C5 + D5 {gr ob} C5 + C5 + D5 {gr ob} C5 + +`} + +## `dy` + +```plain title="Syntax" +dy dynamic +``` + +**Description:** Defines the play dynamics for this beat. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `dynamic` | The dynamic value to apply | `Ident` | yes | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `dynamic` | | + +**Example:** + +{` +\\chord ("C" 0 1 0 2 3 x) +\\ts 2 4 +(0.1 1.2 0.3 2.4 3.5){ch "C"} (0.1 1.2 0.3 2.4 3.5) | +(0.1 2.2 2.3 2.4 0.5){ch "A"} + +`} + +## `tempo` + +```plain title="Syntax" +// [1]: +tempo (bpm hide) +// [2]: +tempo (bpm label hide) +``` + +**Description:** Add a tempo change to the beat. + +**Parameters:** + +| Overload | Name | Description | Type | Required | +|----------|------|-------------|------|----------| +| `[1]` | `bpm` | The new tempo in BPM | `Number` | yes | +| `[1]` | `hide` | If specified, the tempo change is not shown in the music sheet | `hide` | no | +| `[2]` | `bpm` | The new tempo in BPM | `Number` | yes | +| `[2]` | `label` | A textual label for the tempo | `String` | yes `""` | +| `[2]` | `hide` | If specified, the tempo change is not shown in the music sheet | `hide` | no | + +**Parameter Values:** + +Following parameters have value limitations + +| Overload | Name | Values | +|----------|------|--------| +| `[1]` | `hide` | | +| `[2]` | `hide` | | + +**Example:** + +{` +C4 {tempo 120} D4 E4 {tempo 140} F4 | C4.8 {tempo 80} C4 D4 {tempo 100} D4 E4 {tempo 120} E4 F4 {tempo 240} F4 + +`} + +## `volume` + +```plain title="Syntax" +volume value +``` + +**Description:** Add a volume change to the beat. + +The change affects all beats after this one. + + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `value` | The absolute volume of the track within the song in the range of 0-16 | `Number` | yes | + +**Example:** + +{` +C4 {volume 8} D4 E4 {tempo 16} F4 + +`} + +## `balance` + +```plain title="Syntax" +balance value +``` + +**Description:** Add a balance (pan) change to the beat. + +The change affects all beats after this one. + + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `value` | The new balance where 0 is left, 16 is right, and 8 is centered. | `Number` | yes | + +**Example:** + +{` +C4 {balance 0} D4 E4 {balance 16} F4 + +`} + +## `tp` + +```plain title="Syntax" +tp speed +``` + +**Description:** Add a tremolo picking to the beat. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `speed` | The tremolo picking speed | `8\|16\|32` | yes | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `speed` | | + +**Example:** + +{` +3.3{tp 8} 3.3{tp 16} 3.3{tp 32} + +`} + +## `barre` + +```plain title="Syntax" +barre (fret mode) +``` + +**Description:** Add a barré chord notation to the beat. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `fret` | The numeric fret for the barre chord | `Number` | yes | +| `mode` | The barre mode | `full\|half` | no `Full` | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `mode` | | + +**Example:** + +{` +1.1 {barre 24} 2.1 {barre 24} 3.1 {barre 24} 4.1 | +1.1 {barre 4 half} 2.1 {barre 4 half} 3.1 {barre 4 half} 4.1 {barre 4 half} | + +`} + +## `rasg` + +```plain title="Syntax" +rasg pattern +``` + +**Description:** Add a rasgueado play pattern to the beat. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `pattern` | The pattern to apply | `Ident` | yes | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `pattern` | | + +**Example:** + +{` +(1.1 3.2 2.3 0.4) * 4 {rasg amii} + +`} + +## `ot` + +```plain title="Syntax" +ot value +``` + +**Description:** Adds a octave change (ottava) to the beat. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `value` | The octave shift to apply | `Ident` | yes | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `value` | | + +**Example:** + +{` +3.3.4{ ot 15ma } 3.3.4{ ot 8vb } + +`} + +## `instrument` + +```plain title="Syntax" +// [1]: Set the midi instrument as midi program number +instrument program +// [2]: Set the midi instrument as midi program name +instrument programName +// [3]: Set the instrument to percussion +instrument percussion +``` + +**Description:** Adds a instrument change to the beat. + +**Parameters:** + +| Overload | Name | Description | Type | Required | +|----------|------|-------------|------|----------| +| `[1]` | `program` | MIDI program number (0-127) | `Number` | yes | +| `[2]` | `programName` | MIDI program name | `String` | yes | +| `[3]` | `percussion` | Percussion | `percussion` | yes | + +**Parameter Values:** + +Following parameters have value limitations + +| Overload | Name | Values | +|----------|------|--------| +| `[2]` | `programName` | | +| `[3]` | `percussion` | | + +**Example:** + +{` +3.3.4{ ot 15ma } 3.3.4{ ot 8vb } + +`} + +## `bank` + +```plain title="Syntax" +bank value +``` + +**Description:** Adds a instrument bank change to the beat. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `value` | The new MIDI bank | `Number` | yes | + +**Example:** + +{` +C4 C4 C4 {instrument 25 bank 2} C4 + +`} + +## `fermata` + +```plain title="Syntax" +fermata (type length) +``` + +**Description:** Adds a fermata to the beat. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `type` | The fermata type | `short\|medium\|long` | yes | +| `length` | The fermata length | `Number` | no | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `type` | | + +**Example:** + +{` +G4 G4 G4 { fermata medium 4 } + +`} + +## `beam` + +```plain title="Syntax" +beam type +``` + +**Description:** Changes the beaming and stem direction for the beat. +Can be specified multiple times. + + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `type` | The mode to apply | `Ident` | yes | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `type` | | + +**Example:** + +{` +:8 3.3{ beam invert } 3.3 | +3.1{ beam up } 3.1 | +3.6{ beam down } 3.6 | +3.3{ beam auto } 3.3 | +3.3{ beam split } 3.3 | + 3.3 3.3 { beam merge } 3.3 3.3 | + 3.3.16 {beam splitsecondary} 3.3 + +`} + diff --git a/docs/alphatex/_note-properties.mdx b/docs/alphatex/_note-properties.mdx new file mode 100644 index 0000000..8c2210e --- /dev/null +++ b/docs/alphatex/_note-properties.mdx @@ -0,0 +1,874 @@ +import { AlphaTexSample } from '@site/src/components/AlphaTexSample'; +import { ParameterValuesTable } from '@site/src/components/ParameterValuesTable'; + +## `nh` + +```plain title="Syntax" +nh () +``` + +**Description:** Applies a natural harmonic effect to the note (for fretted instruments). + +**Example:** + +{` +:8 3.3{nh} 3.3{ah} 3.3{ph} 3.3{th} 3.3{sh} + +`} + +## `ah` + +```plain title="Syntax" +ah value +``` + +**Description:** Applies an artificial harmonic effect to the note (for fretted instruments). + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `value` | The harmonic value determines a relative fret-offset changing the note pitch when played. For natural harmonics the played fret determines the harmonic value. The rules are a bit special but mostly are aligned with the frequency adjustments happening when harmonics are played at respective frets:

* `2.4` adds 36 frets
* `2.7` adds 34 frets
* `< 3` adds 0 frets
* `<= 3.5` adds 31 frets
* `<= 4` adds 28 frets
* `<= 5` adds 34 frets
* `<= 7` adds 19 frets
* `<= 8.5` adds 36 frets
* `<= 9` adds 28 frets
* `<= 10` adds 34 frets
* `<= 11` adds 0 frets
* `<= 12` adds 12 frets
* `< 14` adds 0 frets
* `<= 15` adds 34 frets
* `<= 16` adds 28 frets
* `<= 17` adds 36 frets
* `<= 18` adds 0 frets
* `<= 19` adds 19 frets
* `<= 21` adds 0 frets
* `<= 22` adds 36 frets
* `<= 24` adds 24 frets
* `other: adds 0 frets | `Number` | no | + +**Example:** + +{` +C4 {volume 8} D4 E4 {tempo 16} F4 + +`} + +## `th` + +```plain title="Syntax" +th value +``` + +**Description:** Applies a tapped harmonic effect to the note (for fretted instruments). + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `value` | The harmonic value determines a relative fret-offset changing the note pitch when played. For natural harmonics the played fret determines the harmonic value. The rules are a bit special but mostly are aligned with the frequency adjustments happening when harmonics are played at respective frets:

* `2.4` adds 36 frets
* `2.7` adds 34 frets
* `< 3` adds 0 frets
* `<= 3.5` adds 31 frets
* `<= 4` adds 28 frets
* `<= 5` adds 34 frets
* `<= 7` adds 19 frets
* `<= 8.5` adds 36 frets
* `<= 9` adds 28 frets
* `<= 10` adds 34 frets
* `<= 11` adds 0 frets
* `<= 12` adds 12 frets
* `< 14` adds 0 frets
* `<= 15` adds 34 frets
* `<= 16` adds 28 frets
* `<= 17` adds 36 frets
* `<= 18` adds 0 frets
* `<= 19` adds 19 frets
* `<= 21` adds 0 frets
* `<= 22` adds 36 frets
* `<= 24` adds 24 frets
* `other: adds 0 frets | `Number` | no | + +**Example:** + +{` +:8 3.3{nh} 3.3{ah} 3.3{ph} 3.3{th} 3.3{sh} + +`} + +## `ph` + +```plain title="Syntax" +ph value +``` + +**Description:** Applies a pinch harmonic effect to the note (for fretted instruments). + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `value` | The harmonic value determines a relative fret-offset changing the note pitch when played. For natural harmonics the played fret determines the harmonic value. The rules are a bit special but mostly are aligned with the frequency adjustments happening when harmonics are played at respective frets:

* `2.4` adds 36 frets
* `2.7` adds 34 frets
* `< 3` adds 0 frets
* `<= 3.5` adds 31 frets
* `<= 4` adds 28 frets
* `<= 5` adds 34 frets
* `<= 7` adds 19 frets
* `<= 8.5` adds 36 frets
* `<= 9` adds 28 frets
* `<= 10` adds 34 frets
* `<= 11` adds 0 frets
* `<= 12` adds 12 frets
* `< 14` adds 0 frets
* `<= 15` adds 34 frets
* `<= 16` adds 28 frets
* `<= 17` adds 36 frets
* `<= 18` adds 0 frets
* `<= 19` adds 19 frets
* `<= 21` adds 0 frets
* `<= 22` adds 36 frets
* `<= 24` adds 24 frets
* `other: adds 0 frets | `Number` | no | + +**Example:** + +{` +:8 3.3{nh} 3.3{ah} 3.3{ph} 3.3{th} 3.3{sh} + +`} + +## `sh` + +```plain title="Syntax" +sh value +``` + +**Description:** Applies a semi harmonic effect to the note (for fretted instruments). + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `value` | The harmonic value determines a relative fret-offset changing the note pitch when played. For natural harmonics the played fret determines the harmonic value. The rules are a bit special but mostly are aligned with the frequency adjustments happening when harmonics are played at respective frets:

* `2.4` adds 36 frets
* `2.7` adds 34 frets
* `< 3` adds 0 frets
* `<= 3.5` adds 31 frets
* `<= 4` adds 28 frets
* `<= 5` adds 34 frets
* `<= 7` adds 19 frets
* `<= 8.5` adds 36 frets
* `<= 9` adds 28 frets
* `<= 10` adds 34 frets
* `<= 11` adds 0 frets
* `<= 12` adds 12 frets
* `< 14` adds 0 frets
* `<= 15` adds 34 frets
* `<= 16` adds 28 frets
* `<= 17` adds 36 frets
* `<= 18` adds 0 frets
* `<= 19` adds 19 frets
* `<= 21` adds 0 frets
* `<= 22` adds 36 frets
* `<= 24` adds 24 frets
* `other: adds 0 frets | `Number` | no | + +**Example:** + +{` +:8 3.3{nh} 3.3{ah} 3.3{ph} 3.3{th} 3.3{sh} + +`} + +## `fh` + +```plain title="Syntax" +fh value +``` + +**Description:** Applies a feedback harmonic effect to the note (for fretted instruments). + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `value` | The harmonic value determines a relative fret-offset changing the note pitch when played. For natural harmonics the played fret determines the harmonic value. The rules are a bit special but mostly are aligned with the frequency adjustments happening when harmonics are played at respective frets:

* `2.4` adds 36 frets
* `2.7` adds 34 frets
* `< 3` adds 0 frets
* `<= 3.5` adds 31 frets
* `<= 4` adds 28 frets
* `<= 5` adds 34 frets
* `<= 7` adds 19 frets
* `<= 8.5` adds 36 frets
* `<= 9` adds 28 frets
* `<= 10` adds 34 frets
* `<= 11` adds 0 frets
* `<= 12` adds 12 frets
* `< 14` adds 0 frets
* `<= 15` adds 34 frets
* `<= 16` adds 28 frets
* `<= 17` adds 36 frets
* `<= 18` adds 0 frets
* `<= 19` adds 19 frets
* `<= 21` adds 0 frets
* `<= 22` adds 36 frets
* `<= 24` adds 24 frets
* `other: adds 0 frets | `Number` | no | + +**Example:** + +{` +:8 3.3{fh} 3.3{ah} 3.3{ph} 3.3{th} 3.3{sh} + +`} + +## `v` + +```plain title="Syntax" +v () +``` + +**Description:** Adds a slight vibrato effect to the note. + +**Example:** + +{` +3.3{v} + +`} + +## `vw` + +```plain title="Syntax" +vw () +``` + +**Description:** Adds a wide vibrato effect to the note. + +**Example:** + +{` +3.3{vw} + +`} + +## `sl` + +```plain title="Syntax" +sl () +``` + +**Description:** Adds a legato slide effect to the note. + +**Example:** + +{` +3.3{sl} 4.3 3.3{ss} 4.3 | +3.3{sib} 3.3{sia} 3.3{sou} 3.3{sod} | +3.3{sib sou} 3.3{sib sod} 3.3{sia sod} 3.3{sia sou} | +x.3{psd} 3.3 | +x.3{psu} 3.3 | + +`} + +## `ss` + +```plain title="Syntax" +ss () +``` + +**Description:** Adds a shift slide effect to the note. + +**Example:** + +{` +3.3{sl} 4.3 3.3{ss} 4.3 | +3.3{sib} 3.3{sia} 3.3{sou} 3.3{sod} | +3.3{sib sou} 3.3{sib sod} 3.3{sia sod} 3.3{sia sou} | +x.3{psd} 3.3 | +x.3{psu} 3.3 | + +`} + +## `sib` + +```plain title="Syntax" +sib () +``` + +**Description:** Adds a slide effect into the note from below. + +**Example:** + +{` +3.3{sl} 4.3 3.3{ss} 4.3 | +3.3{sib} 3.3{sia} 3.3{sou} 3.3{sod} | +3.3{sib sou} 3.3{sib sod} 3.3{sia sod} 3.3{sia sou} | +x.3{psd} 3.3 | +x.3{psu} 3.3 | + +`} + +## `sia` + +```plain title="Syntax" +sia () +``` + +**Description:** Adds a slide effect into the note from above. + +**Example:** + +{` +3.3{sl} 4.3 3.3{ss} 4.3 | +3.3{sib} 3.3{sia} 3.3{sou} 3.3{sod} | +3.3{sib sou} 3.3{sib sod} 3.3{sia sod} 3.3{sia sou} | +x.3{psd} 3.3 | +x.3{psu} 3.3 | + +`} + +## `sou` + +```plain title="Syntax" +sou () +``` + +**Description:** Adds a slide effect out from note upwards. + +**Example:** + +{` +3.3{sl} 4.3 3.3{ss} 4.3 | +3.3{sib} 3.3{sou} 3.3{sou} 3.3{sod} | +3.3{sib sou} 3.3{sib sod} 3.3{sou sod} 3.3{sou sou} | +x.3{psd} 3.3 | +x.3{psu} 3.3 | + +`} + +## `sod` + +```plain title="Syntax" +sod () +``` + +**Description:** Adds a slide effect out from note downwards. + +**Example:** + +{` +3.3{sl} 4.3 3.3{ss} 4.3 | +3.3{sib} 3.3{sod} 3.3{sod} 3.3{sod} | +3.3{sib sod} 3.3{sib sod} 3.3{sod sod} 3.3{sod sod} | +x.3{psd} 3.3 | +x.3{psu} 3.3 | + +`} + +## `psu` + +```plain title="Syntax" +psu () +``` + +**Description:** Adds a pick slide effect out from note upwards. + +**Example:** + +{` +3.3{sl} 4.3 3.3{ss} 4.3 | +3.3{sib} 3.3{psu} 3.3{psu} 3.3{psu} | +3.3{sib psu} 3.3{sib psu} 3.3{psu psu} 3.3{psu psu} | +x.3{psd} 3.3 | +x.3{psu} 3.3 | + +`} + +## `psd` + +```plain title="Syntax" +psd () +``` + +**Description:** Adds a pick slide effect out from note downwards. + +**Example:** + +{` +3.3{sl} 4.3 3.3{ss} 4.3 | +3.3{sib} 3.3{psd} 3.3{psd} 3.3{psd} | +3.3{sib psd} 3.3{sib psd} 3.3{psd psd} 3.3{psd psd} | +x.3{psd} 3.3 | +x.3{psd} 3.3 | + +`} + +## `h` + +```plain title="Syntax" +h () +``` + +**Description:** Applies a hammer on / pull-off effect to the note. + +The fret of the following note on the same string defines whether it is a hammer-on or pull-of. + + +**Example:** + +{` +3.3{h} 4.3 4.3{h} 3.3 | 3.3{h} 4.3{h} 3.3{h} 4.3 + +`} + +## `lht` + +```plain title="Syntax" +lht () +``` + +**Description:** Applies a left-hand-tapped annotation to the note. + +**Example:** + +{` +:16 15.1{h} 13.1{h} 12.1{h} 15.2{lht} + +`} + +## `g` + +```plain title="Syntax" +g () +``` + +**Description:** Marks the note as a ghost note. + +**Example:** + +{` +3.3{g} + +`} + +## `ac` + +```plain title="Syntax" +ac () +``` + +**Description:** Applies a simple accentuation to the note. + +**Example:** + +{` +3.3{ac} 3.3{hac} 3.3{ten} + +`} + +## `hac` + +```plain title="Syntax" +hac () +``` + +**Description:** Applies a heavy accentuation to the note. + +**Example:** + +{` +3.3{ac} 3.3{hac} 3.3{ten} + +`} + +## `ten` + +```plain title="Syntax" +ten () +``` + +**Description:** Applies a tenuto accentuation to the note. + +**Example:** + +{` +3.3{ac} 3.3{ten} 3.3{ten} + +`} + +## `tr` + +```plain title="Syntax" +tr (fret duration) +``` + +**Description:** Applies a trill effect to the note. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `fret` | The fret on which to trill | `Number` | yes | +| `duration` | The duration/speed of the trills | `16\|32\|64` | no `16` | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `duration` | | + +**Example:** + +{` +:4 3.3{tr 4} 3.3{tr 4 16} 3.3{tr 5 32} 3.3{tr 6 64} + +`} + +## `pm` + +```plain title="Syntax" +pm () +``` + +**Description:** Applies a palm mute effect to the note. + +**Example:** + +{` +3.3{pm} 3.3{pm} 3.3{pm} 3.3{pm} + +`} + +## `st` + +```plain title="Syntax" +st () +``` + +**Description:** Applies a staccato effect to the note. + +**Example:** + +{` +3.3{st} + +`} + +## `lr` + +```plain title="Syntax" +lr () +``` + +**Description:** Applies a LetRing effect to the note. + +**Example:** + +{` +3.4{lr} 3.3{lr} 3.2{lr} 3.1{lr} + +`} + +## `x` + +```plain title="Syntax" +x () +``` + +**Description:** Marks the note as a dead note. + +**Example:** + +{` +x.3 3.3{x} + +`} + +## `t` + +```plain title="Syntax" +t () +``` + +**Description:** Marks the note as a tied note. + +This is an alternative syntax to directly specifying the fret as `-`. + +For non stringed instrument it can be a bit more tricky as we cannot use the string to identify which note to tie. There are multiple ways to work around this problem. AlphaTab will try to find the start note for the tie via several rules, if this does not match the desired behavior, you can specify the note value as alternative and indicate the tie via a note effect. + + +**Example:** + +{` +3.3 -.3 | (1.1 3.2 2.3 0.4) (-.1 -.4) + +`} +{` +\\tuning piano +. +// If there is a single note on the previous beat, we tie to this one +// Then a simple - is enough for a tie +:2 a4 - | +// Alternatively you can specify a '-' or 't' as note effect to indicate a tie +:2 a4 a4{-} | +:2 a4 a4{t} | +// This also works for chords using correct note ordering +:2 (a4 a3) (- a3) | +:2 (a4 a3) (a4 -) | +// If nothing helps, always the explicit note value and tie effect should allow +// specifying the correct behavior +:2 (a4 a3) (a4{t} a3) | +:4 (a4 a3) (b2 b3) a4{t} a3{-} | + +`} + +## `turn` + +```plain title="Syntax" +turn () +``` + +**Description:** Applies a turn ornament to the note. + +**Example:** + +{` +:1 C4{turn} | + +`} + +## `iturn` + +```plain title="Syntax" +iturn () +``` + +**Description:** Applies an inverted turn ornament to the note. + +**Example:** + +{` +:1 C4{iturn} | + +`} + +## `umordent` + +```plain title="Syntax" +umordent () +``` + +**Description:** Applies an upper mordent ornament to the note. + +**Example:** + +{` +:1 C4{umordent} | + +`} + +## `lmordent` + +```plain title="Syntax" +lmordent () +``` + +**Description:** Applies an lower mordent ornament to the note. + +**Example:** + +{` +:1 C4{lmordent} | + +`} + +## `string` + +```plain title="Syntax" +string () +``` + +**Description:** Adds an annotation showing the string number of the note above the staff. + +**Example:** + +{` +3.3{string} 3.4{string} 3.5{string} + +`} + +## `hide` + +```plain title="Syntax" +hide () +``` + +**Description:** Hides the note from being displayed in the music sheet. + +**Example:** + +{` +:8 3.3 (4.4{hide} 5.5) + +`} + +## `b` + +```plain title="Syntax" +// [1]: +b (values) +// [2]: +b (type values) +// [3]: +b (style values) +// [4]: +b (type style values) +``` + +**Description:** Adds a bend effect to the note. + +* The `b` variant automatically spreads the values across the duration of the beat. +* The `be` (exact) variant allows specifying exactly at which offset a value is placed. + +It is recommended to rely on the auto-detection of the type and only specify the type explicitly if something is wrong. + + +**Parameters:** + +| Overload | Name | Description | Type | Required | +|----------|------|-------------|------|----------| +| `[1]` | `values` | The values of the bend in quarter-tones relative to the original note, decimals supported | `Number[]` | no | +| `[2]` | `type` | The type of bend (affects the display). | `Ident` | yes | +| `[2]` | `values` | The values of the bend in quarter-tones relative to the original note, decimals supported | `Number[]` | no | +| `[3]` | `style` | The style of the bend. | `default\|gradual\|fast` | yes | +| `[3]` | `values` | The values of the bend in quarter-tones relative to the original note, decimals supported | `Number[]` | no | +| `[4]` | `type` | The type of bend (affects the display). | `Ident` | yes | +| `[4]` | `style` | The style of the bend. | `default\|gradual\|fast` | yes | +| `[4]` | `values` | The values of the bend in quarter-tones relative to the original note, decimals supported | `Number[]` | no | + +**Parameter Values:** + +Following parameters have value limitations + +| Overload | Name | Values | +|----------|------|--------| +| `[2]` | `type` | | +| `[3]` | `style` | | +| `[4]` | `type` | | +| `[4]` | `style` | | + +**Example:** + +{` +3.3{b (0 4)} | +3.3{b (0 4 0 8)} | + +`} + +## `be` + +```plain title="Syntax" +// [1]: +be (valueAndOffset) +// [2]: +be (type valueAndOffset) +// [3]: +be (style valueAndOffset) +// [4]: +be (type style valueAndOffset) +``` + +**Description:** Adds an exact bend effect to the note. + +* The `b` variant automatically spreads the values across the duration of the beat. +* The `be` (exact) variant allows specifying exactly at which offset a value is placed. + +It is recommended to rely on the auto-detection of the type and only specify the type explicitly if something is wrong. + + +**Parameters:** + +| Overload | Name | Description | Type | Required | +|----------|------|-------------|------|----------| +| `[1]` | `valueAndOffset` | The offset at which the value becomes valid in range of 0-60 and
The value of the bend in quarter-tones relative to the original note.
The offset and value are actually two parameters:
`3.3 {be (0 0 5 2 30 4)}`
| `Number[]` | no | +| `[2]` | `type` | The type of bend (affects the display). | `Ident` | yes | +| `[2]` | `valueAndOffset` | The offset at which the value becomes valid in range of 0-60 and
The value of the bend in quarter-tones relative to the original note.
The offset and value are actually two parameters:
`3.3 {be (0 0 5 2 30 4)}`
| `Number[]` | no | +| `[3]` | `style` | The style of the whammy play style. | `default\|gradual\|fast` | yes | +| `[3]` | `valueAndOffset` | The offset at which the value becomes valid in range of 0-60 and
The value of the bend in quarter-tones relative to the original note.
The offset and value are actually two parameters:
`3.3 {be (0 0 5 2 30 4)}`
| `Number[]` | no | +| `[4]` | `type` | The type of bend (affects the display). | `Ident` | yes | +| `[4]` | `style` | The style of the whammy play style. | `default\|gradual\|fast` | yes | +| `[4]` | `valueAndOffset` | The offset at which the value becomes valid in range of 0-60 and
The value of the bend in quarter-tones relative to the original note.
The offset and value are actually two parameters:
`3.3 {be (0 0 5 2 30 4)}`
| `Number[]` | no | + +**Parameter Values:** + +Following parameters have value limitations + +| Overload | Name | Values | +|----------|------|--------| +| `[2]` | `type` | | +| `[3]` | `style` | | +| `[4]` | `type` | | +| `[4]` | `style` | | + +**Example:** + +{` +:1 3.3 {be (0 0 5 2 30 4)} + +`} + +## `lf` + +```plain title="Syntax" +lf finger +``` + +**Description:** Adds a left-hand fingering annotation to the note. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `finger` | The finger | `Number` | yes | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `finger` | | + +**Example:** + +{` +:8 3.3{lf 1} 3.3{lf 2} 3.3{lf 3} 3.3{lf 4} 3.3{lf 5} (2.2{lf 4} 2.3{lf 3} 2.4{lf 2}) | +:8 3.3{rf 1} 3.3{rf 2} 3.3{rf 3} 3.3{rf 4} 3.3{lf 5} + +`} + +## `rf` + +```plain title="Syntax" +rf finger +``` + +**Description:** Adds a right-hand fingering annotation to the note. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `finger` | The finger | `Number` | yes | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `finger` | | + +**Example:** + +{` +:8 3.3{lf 1} 3.3{lf 2} 3.3{lf 3} 3.3{lf 4} 3.3{lf 5} (2.2{lf 4} 2.3{lf 3} 2.4{lf 2}) | +:8 3.3{rf 1} 3.3{rf 2} 3.3{rf 3} 3.3{rf 4} 3.3{lf 5} + +`} + +## `acc` + +```plain title="Syntax" +acc mode +``` + +**Description:** Changes the mode to determine the accidentals for this note. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `mode` | The accidental mode | `Ident` | yes | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `mode` | | + +**Example:** + +{` +:8 3.3{lf 1} 3.3{lf 2} 3.3{lf 3} 3.3{lf 4} 3.3{lf 5} (2.2{lf 4} 2.3{lf 3} 2.4{lf 2}) | +:8 3.3{rf 1} 3.3{rf 2} 3.3{rf 3} 3.3{rf 4} 3.3{lf 5} + +`} + +## `slur` + +```plain title="Syntax" +// [1]: +slur id +// [2]: +slur id +``` + +**Description:** Marks the start or end of a slur for the note. + +**Parameters:** + +| Overload | Name | Description | Type | Required | +|----------|------|-------------|------|----------| +| `[1]` | `id` | A unique ID to mark the start and end of the slur. | `String` | yes | +| `[2]` | `id` | A unique ID to mark the start and end of the slur. | `Ident` | yes | + +**Example:** + +{` +(3.3 {slur s1} 4.4).4 7.3.8 8.3.8 10.3 {slur s1} .8 + +`} + +## `-` + +```plain title="Syntax" +- () +``` + +**Description:** Marks the note as a tied note. + +This is an alternative syntax to directly specifying the fret as `-`. + +For non stringed instrument it can be a bit more tricky as we cannot use the string to identify which note to tie. There are multiple ways to work around this problem. AlphaTab will try to find the start note for the tie via several rules, if this does not match the desired behavior, you can specify the note value as alternative and indicate the tie via a note effect. + + +**Example:** + +{` +3.3 -.3 | (1.1 3.2 2.3 0.4) (-.1 -.4) + +`} +{` +\\tuning piano +. +// If there is a single note on the previous beat, we tie to this one +// Then a simple - is enough for a tie +:2 a4 - | +// Alternatively you can specify a '-' or 't' as note effect to indicate a tie +:2 a4 a4{-} | +:2 a4 a4{t} | +// This also works for chords using correct note ordering +:2 (a4 a3) (- a3) | +:2 (a4 a3) (a4 -) | +// If nothing helps, always the explicit note value and tie effect should allow +// specifying the correct behavior +:2 (a4 a3) (a4{t} a3) | +:4 (a4 a3) (b2 b3) a4{t} a3{-} | + +`} + diff --git a/docs/alphatex/_score-metadata.mdx b/docs/alphatex/_score-metadata.mdx new file mode 100644 index 0000000..f00e5e4 --- /dev/null +++ b/docs/alphatex/_score-metadata.mdx @@ -0,0 +1,764 @@ +import { AlphaTexSample } from '@site/src/components/AlphaTexSample'; +import { ParameterValuesTable } from '@site/src/components/ParameterValuesTable'; + +## `\title` + +```plain title="Syntax" +\title (value template textAlign) +``` + +**Description:** Set the title of the song. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `value` | The value to set | `String` | yes | +| `template` | The template used to render the text | `String` | no | +| `textAlign` | The alignment of the text on the music sheet | `left\|center\|right` | no | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `textAlign` | | + +**Example:** + +{` +\\title ("Song Title" "Title: %TITLE%" left) +C4 + +`} + +## `\subtitle` + +```plain title="Syntax" +\subtitle (value template textAlign) +``` + +**Description:** Set the subtitle of the song. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `value` | The value to set | `String` | yes | +| `template` | The template used to render the text | `String` | no | +| `textAlign` | The alignment of the text on the music sheet | `left\|center\|right` | no | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `textAlign` | | + +**Example:** + +{` +\\title ("Song Title" "Title: %TITLE%" left) +\\subtitle ("Subtitle" "[%SUBTITLE%]" left) +C4 + +`} + +## `\artist` + +```plain title="Syntax" +\artist (value template textAlign) +``` + +**Description:** Set the artist of the song. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `value` | The value to set | `String` | yes | +| `template` | The template used to render the text | `String` | no | +| `textAlign` | The alignment of the text on the music sheet | `left\|center\|right` | no | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `textAlign` | | + +**Example:** + +{` +\\title ("Song Title" "Title: %TITLE%" left) +\\artist "alphaTab" + C4 + +`} + +## `\album` + +```plain title="Syntax" +\album (value template textAlign) +``` + +**Description:** Set the album of the song. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `value` | The value to set | `String` | yes | +| `template` | The template used to render the text | `String` | no | +| `textAlign` | The alignment of the text on the music sheet | `left\|center\|right` | no | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `textAlign` | | + +**Example:** + +{` +\\title ("Song Title" "Title: %TITLE%" left) +\\album "alphaTab vol.1" +C4 + +`} + +## `\words` + +```plain title="Syntax" +\words (value template textAlign) +``` + +**Description:** Set the lyrics author of the song. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `value` | The value to set | `String` | yes | +| `template` | The template used to render the text | `String` | no | +| `textAlign` | The alignment of the text on the music sheet | `left\|center\|right` | no | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `textAlign` | | + +**Example:** + +{` +\\words "CoderLine" +C4 + +`} + +## `\music` + +```plain title="Syntax" +\music (value template textAlign) +``` + +**Description:** Set the music author of the song. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `value` | The value to set | `String` | yes | +| `template` | The template used to render the text | `String` | no | +| `textAlign` | The alignment of the text on the music sheet | `left\|center\|right` | no | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `textAlign` | | + +**Example:** + +{` +\\music "CoderLine and Contributors" +C4 + +`} + +## `\wordsAndMusic` + +```plain title="Syntax" +\wordsAndMusic (template textAlign) +``` + +**Description:** Sets the template and text align for combined words and music authors. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `template` | The template used to render the text | `String` | yes | +| `textAlign` | The alignment of the text on the music sheet | `left\|center\|right` | no | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `textAlign` | | + +**Example:** + +{` +\\words "CoderLine" +\\music "CoderLine" +\\wordsAndMusic ("Words & Music: %WORDS%") +C4 + +`} + +## `\copyright` + +```plain title="Syntax" +\copyright (value template textAlign) +``` + +**Description:** Set the copyright owner of the song. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `value` | The value to set | `String` | yes | +| `template` | The template used to render the text | `String` | no | +| `textAlign` | The alignment of the text on the music sheet | `left\|center\|right` | no | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `textAlign` | | + +**Example:** + +{` +\\copyright "CoderLine" +C4 + +`} + +## `\copyright2` + +```plain title="Syntax" +\copyright2 (template textAlign) +``` + +**Description:** Sets the template and text align for the second copyright line. + + There is no own "value" as it is typically used to just define a static text like "All rights reserved". The "template" can be used for defining the display. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `template` | The template used to render the text | `String` | yes | +| `textAlign` | The alignment of the text on the music sheet | `left\|center\|right` | no | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `textAlign` | | + +**Example:** + +{` +\\copyright "CoderLine" +\\copyright2 "All rights reserved" +C4 + +`} + +## `\instructions` + +```plain title="Syntax" +\instructions value +``` + +**Description:** Sets additional textual instructions for the song (not displayed). + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `value` | The value to set | `String` | yes | + +**Example:** + +{` +\\instructions "Practice this piece until you get it perfect." +C4 + +`} + +## `\notices` + +```plain title="Syntax" +\notices value +``` + +**Description:** Sets general notices for the song (not displayed). + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `value` | The value to set | `String` | yes | + +**Example:** + +{` +\\notices "I hope you appreciate this music sheet, it was a lot of effort to create!" +C4 + +`} + +## `\tab` + +```plain title="Syntax" +\tab (value template textAlign) +``` + +**Description:** Set the transcriber of the music sheet. + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `value` | The value to set | `String` | yes | +| `template` | The template used to render the text | `String` | no | +| `textAlign` | The alignment of the text on the music sheet | `left\|center\|right` | no | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `textAlign` | | + +**Example:** + +{` +\\tab "Transcribed by me" +C4 + +`} + +## `\systemsLayout` + +```plain title="Syntax" +\systemsLayout (numberOfBars) +``` + +**Description:** Defines the number of bars to display per system when rendering multiple tracks. + +The `systemsLayout` and `defaultSystemsLayout` allow configuring the system layout. The system layout, defines how many bars should be displayed per system (line) if enabled via [`systemsLayoutMode`](/docs/reference/settings/display/systemslayoutmode). + + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `numberOfBars` | Defines for every system (line) the number of bars it should contain | `Number[]` | no | + +**Example:** + +{` +\\systemsLayout (2 3 2) +\\track + :1 c4 | c4 | c4 | c4 | c4 | c4 | c4 +\\track + :1 c4 | c4 | c4 | c4 | c4 | c4 | c4 + +`} + +## `\defaultSystemsLayout` + +```plain title="Syntax" +\defaultSystemsLayout numberOfBars +``` + +**Description:** Defines the default number of bars to display per system when rendering multiple tracks. + +The `systemsLayout` and `defaultSystemsLayout` allow configuring the system layout. The system layout, defines how many bars should be displayed per system (line) if enabled via [`systemsLayoutMode`](/docs/reference/settings/display/systemslayoutmode). + + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `numberOfBars` | The number of bars the system should contain. | `Number` | yes | + +**Example:** + +{` +\\defaultSystemsLayout 2 +\\track + :1 c4 | c4 | c4 | c4 | c4 | c4 | c4 +\\track + :1 c4 | c4 | c4 | c4 | c4 | c4 | c4 + +`} + +## `\showDynamics` + +```plain title="Syntax" +\showDynamics () +``` + +**Description:** Enables the display of dynamics. + +**Example:** + +{` +\\showDynamics + C4 {dy FFF} D4 + E4 {dy PP} F4 + +`} + +## `\hideDynamics` + +```plain title="Syntax" +\hideDynamics () +``` + +**Description:** Disables the display of dynamics. + +**Example:** + +{` +\\hideDynamics + C4 {dy FFF} D4 + E4 {dy PP} F4 + +`} + +## `\useSystemSignSeparator` + +```plain title="Syntax" +\useSystemSignSeparator () +``` + +**Description:** Configures whether a system sign separator should be added (in case multiple tracks are shown). + +**Example:** + +{` +\\useSystemSignSeparator +\\defaultSystemsLayout 2 +\\track "T1" +:1 C4 | C4 | C4 +\\track "T2" +:1 C4 | C4 | C4 + +`} + +## `\multiBarRest` + +```plain title="Syntax" +\multiBarRest () +``` + +**Description:** Show multibar rests when rendering multiple tracks. + +**Example:** + +{` +\\title "Multi Track" +\\multiBarRest +\\track "Piano 1" "pno1" + \\staff {score} + C4 D4 E4 F4 | r | r | C4 D4 E4 F4 | r | r | r | C4 + +\\track "Piano 2" "pno1" + \\staff {score} + C4 D4 E4 F4 | r | r | C4 D4 E4 F4 | r | r | r | r | + +`} + +## `\bracketExtendMode` + +```plain title="Syntax" +\bracketExtendMode mode +``` + +**Description:** Set the mode for [brackets and braces](/docs/showcase/general#brackets-and-braces). + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `mode` | The mode to use | `noBrackets\|groupStaves\|groupSimilarInstruments` | yes | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `mode` | | + +**Example:** + +{` +\\bracketextendmode GroupSimilarInstruments +\\track "Piano1" + \\staff {score} +\\instrument piano + C4 D4 E4 F4 + \\staff {score} + \\clef f4 C3 D3 E3 F3 +\\track "Piano2" + \\staff {score} +\\instrument piano + C4 D4 E4 F4 +\\track "Flute 1" + \\staff { score } +\\instrument flute + C4 D4 E4 F4 +\\track "Flute 2" + \\staff { score } +\\instrument flute + \\clef f4 C3 D3 E3 F3 +\\track "Guitar 1" + \\staff { score tabs } + 0.3.4 2.3.4 5.3.4 7.3.4 + +`} + +## `\singleTrackTrackNamePolicy` + +```plain title="Syntax" +\singleTrackTrackNamePolicy mode +``` + +**Description:** Configures on which systems to show the [track names](/docs/showcase/general#track-names) when only a single track is rendered. + + +**Parameters:** + +| Name | Description | Type | Required | +|------|-------------|------|----------| +| `mode` | The mode to use | `hidden\|firstSystem\|allSystems` | yes | + +**Parameter Values:** + +Following parameters have value limitations + +| Name | Values | +|------|--------| +| `mode` |