Skip to content

Commit 60c2250

Browse files
Danielku15Danielku15
authored
docs: alphaTex exporter documentation (#143)
2 parents e549e4e + 47069f2 commit 60c2250

10 files changed

Lines changed: 172 additions & 16 deletions

File tree

‎docs/guides/exporter.mdx‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,12 @@ After alphaTab has loaded a full [`Score`](/docs/reference/score) object from an
1313
Supported export formats:
1414

1515
- Guitar Pro 7 (alphaTab.exporter.Gp7Exporter) <span className="badge badge--info">since 1.2.0</span>
16+
- alphaTex (alphaTab.exporter.AlphaTexExporter) <span className="badge badge--info">since 1.7.0</span>
1617

1718
To export a `Score` object the corresponding exporter needs to be created and called. Then the resulting binary array can be used further to
1819
trigger a download, send it to a server, save it to a file etc.
1920

21+
## Guitar Pro 7 (since 1.2.0)
2022

2123
<Tabs
2224
defaultValue="js"
@@ -56,3 +58,28 @@ using(var fs = new System.IO.FileStream(fileName, System.IO.FileMode.Create))
5658

5759
</TabItem>
5860
</Tabs>
61+
62+
## alphaTex Exporter (since 1.7.0)
63+
64+
Starting with 1.7.0 alphaTab can also export the data model to its own music notation language [alphaTex](/docs/alphatex/introduction).
65+
The exporter supports all features which the importer can also handle. If you find something, please open a feature request.
66+
67+
Via the exporter settings [`settings.exporter`](/docs/reference/settings#Exporter) the format of the exported code can be adjusted.
68+
Especially the `comments` can be quite useful for alphaTex beginners to learn about the syntax.
69+
70+
While you can use the standard `export` to export the code into a byte array, you can also use `exportToString` to get the alphaTex code
71+
back as plain string.
72+
73+
```js
74+
const exporter = new alphaTab.exporter.AlphaTexExporter();
75+
const data = exporter.export(api.score, api.settings); // will return a Uint8Array
76+
const texCode = exporter.exportToString(api.score, api.settings); // will return a string
77+
78+
// trigger download
79+
const a = document.createElement('a');
80+
a.download = api.score.title.length > 0 ? api.score.title + '.atex' : 'Untitled.atex';
81+
a.href = URL.createObjectURL(new Blob([data]));
82+
document.body.appendChild(a);
83+
a.click();
84+
document.body.removeChild(a);
85+
```

‎docs/reference/api/exportaudio.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: "Starts the audio export for the currently loaded song."
44
sidebar_custom_props:
55
kind: method
66
category: Methods - Player
7-
since: 1.5.0
7+
since: 1.6.0
88
---
99

1010
import { ParameterTable, ParameterRow } from '@site/src/components/ParameterTable';
@@ -16,7 +16,7 @@ import { SinceBadge } from '@site/src/components/SinceBadge';
1616
import DynHeading from '@site/src/components/DynHeading';
1717
import Link from '@docusaurus/Link';
1818

19-
<SinceBadge since="1.5.0" />
19+
<SinceBadge since="1.6.0" />
2020

2121
### Description
2222
Starts the audio export for the currently loaded song. This will not export or use any backing track media but will always use the synthesizer to generate the output.

‎docs/reference/settings/core/smuflfontsources.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,5 +27,9 @@ they are available for rendering the music sheet. The sources can be set to any
2727
CSS compatible URL which can be passed into `url()`.
2828
See https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src#url
2929

30+
If you customize the SmuFL font used in alphaTab, you will also need to provide
31+
the respective SMuFL Metadata information to alphaTab.
32+
Set the metadata via <code style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><Link style={{"color":"#36acaa"}} to={"/docs/reference/types/engravingsettings/fillfromsmufl"}>{"fillFromSmufl"}</Link></code> on the rendering resources.
33+
3034
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#36acaa"}}>{"smuflFontSources"}</span><span style={{"color":"#393A34"}}>{":"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><Link style={{"color":"#36acaa"}} to={"/docs/reference/types/fontfileformat"}>{"Map"}</Link><span style={{"color":"#393A34"}}>{"<"}</span><Link style={{"color":"#36acaa"}} to={"/docs/reference/types/fontfileformat"}>{"FontFileFormat"}</Link><span style={{"color":"#393A34"}}>{","}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"string"}</span><span style={{"color":"#393A34"}}>{">"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"|"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#00009f"}}>{"null"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"="}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"Bravura files located at <code style={{\"color\":\"#393A34\",\"backgroundColor\":\"#f6f8fa\"}}><Link style={{\"color\":\"#36acaa\"}} to={\"/docs/reference/settings/core/fontdirectory\"}>{\"fontDirectory\"}</Link></code> ."}</span><span style={{"color":"#393A34"}}>{";"}</span></code></pre></div></div>
3135

‎docs/reference/settings/display/effectbandpaddingbottom.mdx‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: display.effectBandPaddingBottom
3+
description: "The padding between individual effect bands."
4+
sidebar_custom_props:
5+
jsOnParent: true
6+
category: Display
7+
since: 1.7.0
8+
---
9+
10+
import { ParameterTable, ParameterRow } from '@site/src/components/ParameterTable';
11+
import CodeBlock from '@theme/CodeBlock';
12+
import Tabs from "@theme/Tabs";
13+
import TabItem from "@theme/TabItem";
14+
import { CodeBadge } from '@site/src/components/CodeBadge';
15+
import { SinceBadge } from '@site/src/components/SinceBadge';
16+
import DynHeading from '@site/src/components/DynHeading';
17+
import Link from '@docusaurus/Link';
18+
19+
import { SettingsHeader } from '@site/src/components/SettingsHeader';
20+
21+
<SettingsHeader />
22+
23+
### Description
24+
The padding between individual effect bands.
25+
26+
<Tabs defaultValue="js" values={[{label: "JavaScript", value: "js"},{label: "C#", value: "cs"},{label:"Kotlin", value: "kt"}]}>
27+
<TabItem value="js">
28+
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#36acaa"}}>{"effectBandPaddingBottom"}</span><span style={{"color":"#393A34"}}>{":"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"number"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"="}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"2"}</span><span style={{"color":"#393A34"}}>{";"}</span></code></pre></div></div>
29+
</TabItem>
30+
<TabItem value="cs">
31+
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#36acaa"}}>{"double"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"EffectBandPaddingBottom"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"{"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#00009f"}}>{"get"}</span><span style={{"color":"#393A34"}}>{";"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#00009f"}}>{"set"}</span><span style={{"color":"#393A34"}}>{";"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"}"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"="}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"2"}</span></code></pre></div></div>
32+
</TabItem>
33+
<TabItem value="kt">
34+
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#00009f"}}>{"var"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"effectBandPaddingBottom"}</span><span style={{"color":"#393A34"}}>{":"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"Double"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"="}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"2"}</span></code></pre></div></div>
35+
</TabItem>
36+
</Tabs>
37+

‎docs/reference/settings/exporter/comments.mdx‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: exporter.comments
3+
description: "Whether to write extended comments into the exported file (e.g. to in alphaTex to mark where certain metadata or bars starts)"
4+
sidebar_custom_props:
5+
category: Exporter
6+
since: 1.7.0
7+
---
8+
9+
import { ParameterTable, ParameterRow } from '@site/src/components/ParameterTable';
10+
import CodeBlock from '@theme/CodeBlock';
11+
import Tabs from "@theme/Tabs";
12+
import TabItem from "@theme/TabItem";
13+
import { CodeBadge } from '@site/src/components/CodeBadge';
14+
import { SinceBadge } from '@site/src/components/SinceBadge';
15+
import DynHeading from '@site/src/components/DynHeading';
16+
import Link from '@docusaurus/Link';
17+
18+
import { SettingsHeader } from '@site/src/components/SettingsHeader';
19+
20+
<SettingsHeader />
21+
22+
### Description
23+
Whether to write extended comments into the exported file (e.g. to in alphaTex to mark where certain metadata or bars starts)
24+
25+
<Tabs defaultValue="js" values={[{label: "JavaScript", value: "js"},{label: "C#", value: "cs"},{label:"Kotlin", value: "kt"}]}>
26+
<TabItem value="js">
27+
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#36acaa"}}>{"comments"}</span><span style={{"color":"#393A34"}}>{":"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"boolean"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"="}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"false"}</span><span style={{"color":"#393A34"}}>{";"}</span></code></pre></div></div>
28+
</TabItem>
29+
<TabItem value="cs">
30+
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#36acaa"}}>{"bool"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"Comments"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"{"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#00009f"}}>{"get"}</span><span style={{"color":"#393A34"}}>{";"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#00009f"}}>{"set"}</span><span style={{"color":"#393A34"}}>{";"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"}"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"="}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"false"}</span></code></pre></div></div>
31+
</TabItem>
32+
<TabItem value="kt">
33+
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#00009f"}}>{"var"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"comments"}</span><span style={{"color":"#393A34"}}>{":"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"Boolean"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"="}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"false"}</span></code></pre></div></div>
34+
</TabItem>
35+
</Tabs>
36+

‎docs/reference/settings/exporter/indent.mdx‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: exporter.indent
3+
description: "How many characters should be indented on formatted outputs. If set to negative values"
4+
sidebar_custom_props:
5+
category: Exporter
6+
since: 1.7.0
7+
---
8+
9+
import { ParameterTable, ParameterRow } from '@site/src/components/ParameterTable';
10+
import CodeBlock from '@theme/CodeBlock';
11+
import Tabs from "@theme/Tabs";
12+
import TabItem from "@theme/TabItem";
13+
import { CodeBadge } from '@site/src/components/CodeBadge';
14+
import { SinceBadge } from '@site/src/components/SinceBadge';
15+
import DynHeading from '@site/src/components/DynHeading';
16+
import Link from '@docusaurus/Link';
17+
18+
import { SettingsHeader } from '@site/src/components/SettingsHeader';
19+
20+
<SettingsHeader />
21+
22+
### Description
23+
How many characters should be indented on formatted outputs. If set to negative values
24+
formatted outputs are disabled.
25+
26+
<Tabs defaultValue="js" values={[{label: "JavaScript", value: "js"},{label: "C#", value: "cs"},{label:"Kotlin", value: "kt"}]}>
27+
<TabItem value="js">
28+
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#36acaa"}}>{"indent"}</span><span style={{"color":"#393A34"}}>{":"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"number"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"="}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"2"}</span><span style={{"color":"#393A34"}}>{";"}</span></code></pre></div></div>
29+
</TabItem>
30+
<TabItem value="cs">
31+
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#36acaa"}}>{"double"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"Indent"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"{"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#00009f"}}>{"get"}</span><span style={{"color":"#393A34"}}>{";"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#00009f"}}>{"set"}</span><span style={{"color":"#393A34"}}>{";"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"}"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"="}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"2"}</span></code></pre></div></div>
32+
</TabItem>
33+
<TabItem value="kt">
34+
<div className="codeBlockContainer"><div className="codeBlockContent"><pre className="codeBlock"><code className="codeBlockLines" style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#00009f"}}>{"var"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"indent"}</span><span style={{"color":"#393A34"}}>{":"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"Double"}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#393A34"}}>{"="}</span><span style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}>{" "}</span><span style={{"color":"#36acaa"}}>{"2"}</span></code></pre></div></div>
35+
</TabItem>
36+
</Tabs>
37+

‎package-lock.json‎

Lines changed: 4 additions & 4 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
"generate-alphatabdoc": "tsx scripts/generate-alphatabdoc.mts"
1717
},
1818
"dependencies": {
19-
"@coderline/alphatab": "^1.6.0-alpha.1416",
19+
"@coderline/alphatab": "^1.7.0-alpha.1515",
2020
"@docusaurus/core": "^3.7.0",
2121
"@docusaurus/preset-classic": "^3.7.0",
2222
"@docusaurus/theme-mermaid": "^3.7.0",

‎scripts/generate-common.mts‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -454,11 +454,11 @@ function tryGetSettingsUrl(
454454
.name!.getText()
455455
.toLowerCase()}/${symbol.name.toLowerCase()}`;
456456
} else {
457-
cconsole.warn(
458-
"Could not find a property of type ",
459-
parentSymbol.name,
460-
" in Settings"
461-
);
457+
// cconsole.warn(
458+
// "Could not find a property of type ",
459+
// parentSymbol.name,
460+
// " in Settings"
461+
// );
462462
return undefined;
463463
}
464464
}

‎src/components/ReferenceTable/index.tsx‎

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ import {
88
} from "@docusaurus/plugin-content-docs";
99
import { useDocById } from "@docusaurus/plugin-content-docs/client";
1010
import { MarkdownString } from "../MarkdownString";
11+
import { useLocation } from "@docusaurus/router";
1112

1213
function buildPropertyUrl(property: Page) {
1314
let url = "";
@@ -24,12 +25,12 @@ type ReferenceRowProps = { property: Page; showJson: boolean };
2425
const ReferenceRow: React.FC<ReferenceRowProps> = ({ property, showJson }) => {
2526
const { mainName, javaScriptOnly } =
2627
buildNames(property);
27-
28+
2829
return (
2930
<tr>
3031
<td>
3132
<a href={buildPropertyUrl(property)}>
32-
<CodeBadge name={mainName} type={javaScriptOnly ? 'js' : 'all' } />
33+
<CodeBadge name={mainName} type={javaScriptOnly ? 'js' : 'all'} />
3334
</a>
3435
</td>
3536
<td><MarkdownString content={property.prop("description", "")} /></td>
@@ -70,7 +71,7 @@ const ReferenceCategory: React.FC<ReferenceCategoryProps> = ({
7071
return (
7172
<>
7273
<tr>
73-
<th colSpan={4}>{name}</th>
74+
<th colSpan={4} id={name}>{name}</th>
7475
</tr>
7576
{rows}
7677
</>
@@ -103,7 +104,7 @@ export const ReferenceTable: React.FC<ReferenceTableProps> = ({
103104
const existingKeys = new Map<string, Page[]>();
104105
const pages: { key: string; items: Page[] }[] = [];
105106
for (const page of allPages) {
106-
if(page.type === "link" && page.docId?.startsWith('_') === true) {
107+
if (page.type === "link" && page.docId?.startsWith('_') === true) {
107108
continue;
108109
}
109110

@@ -131,6 +132,20 @@ export const ReferenceTable: React.FC<ReferenceTableProps> = ({
131132
/>
132133
));
133134

135+
const { hash } = useLocation();
136+
useEffect(() => {
137+
const id = hash.replace('#', '');
138+
const element = document.getElementById(id);
139+
if (element) {
140+
setTimeout(() => {
141+
element.scrollIntoView({
142+
behavior: 'auto',
143+
block: 'center',
144+
});
145+
}, 100);
146+
}
147+
}, []);
148+
134149
return (
135150
<table className="table table-striped table-condensed reference-table">
136151
<thead>

0 commit comments

Comments
 (0)