From 47069f2489444a7dac66895fd10ba7c41b92a8a9 Mon Sep 17 00:00:00 2001 From: Danielku15 Date: Mon, 18 Aug 2025 20:33:43 +0200 Subject: [PATCH] docs: alphaTex exporter documentation --- docs/guides/exporter.mdx | 27 ++++++++++++++ docs/reference/api/exportaudio.mdx | 4 +- .../settings/core/smuflfontsources.mdx | 4 ++ .../display/effectbandpaddingbottom.mdx | 37 +++++++++++++++++++ docs/reference/settings/exporter/comments.mdx | 36 ++++++++++++++++++ docs/reference/settings/exporter/indent.mdx | 37 +++++++++++++++++++ package-lock.json | 8 ++-- package.json | 2 +- scripts/generate-common.mts | 10 ++--- src/components/ReferenceTable/index.tsx | 23 ++++++++++-- 10 files changed, 172 insertions(+), 16 deletions(-) create mode 100644 docs/reference/settings/display/effectbandpaddingbottom.mdx create mode 100644 docs/reference/settings/exporter/comments.mdx create mode 100644 docs/reference/settings/exporter/indent.mdx diff --git a/docs/guides/exporter.mdx b/docs/guides/exporter.mdx index d7c2864..0c0bd1b 100644 --- a/docs/guides/exporter.mdx +++ b/docs/guides/exporter.mdx @@ -13,10 +13,12 @@ After alphaTab has loaded a full [`Score`](/docs/reference/score) object from an Supported export formats: - Guitar Pro 7 (alphaTab.exporter.Gp7Exporter) since 1.2.0 +- alphaTex (alphaTab.exporter.AlphaTexExporter) since 1.7.0 To export a `Score` object the corresponding exporter needs to be created and called. Then the resulting binary array can be used further to trigger a download, send it to a server, save it to a file etc. +## Guitar Pro 7 (since 1.2.0) + +## alphaTex Exporter (since 1.7.0) + +Starting with 1.7.0 alphaTab can also export the data model to its own music notation language [alphaTex](/docs/alphatex/introduction). +The exporter supports all features which the importer can also handle. If you find something, please open a feature request. + +Via the exporter settings [`settings.exporter`](/docs/reference/settings#Exporter) the format of the exported code can be adjusted. +Especially the `comments` can be quite useful for alphaTex beginners to learn about the syntax. + +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 +back as plain string. + +```js +const exporter = new alphaTab.exporter.AlphaTexExporter(); +const data = exporter.export(api.score, api.settings); // will return a Uint8Array +const texCode = exporter.exportToString(api.score, api.settings); // will return a string + +// trigger download +const a = document.createElement('a'); +a.download = api.score.title.length > 0 ? api.score.title + '.atex' : 'Untitled.atex'; +a.href = URL.createObjectURL(new Blob([data])); +document.body.appendChild(a); +a.click(); +document.body.removeChild(a); +``` \ No newline at end of file diff --git a/docs/reference/api/exportaudio.mdx b/docs/reference/api/exportaudio.mdx index 095d6bb..eee6438 100644 --- a/docs/reference/api/exportaudio.mdx +++ b/docs/reference/api/exportaudio.mdx @@ -4,7 +4,7 @@ description: "Starts the audio export for the currently loaded song." sidebar_custom_props: kind: method category: Methods - Player - since: 1.5.0 + since: 1.6.0 --- import { ParameterTable, ParameterRow } from '@site/src/components/ParameterTable'; @@ -16,7 +16,7 @@ import { SinceBadge } from '@site/src/components/SinceBadge'; import DynHeading from '@site/src/components/DynHeading'; import Link from '@docusaurus/Link'; - + ### Description 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. diff --git a/docs/reference/settings/core/smuflfontsources.mdx b/docs/reference/settings/core/smuflfontsources.mdx index 5c18848..8e35b08 100644 --- a/docs/reference/settings/core/smuflfontsources.mdx +++ b/docs/reference/settings/core/smuflfontsources.mdx @@ -27,5 +27,9 @@ they are available for rendering the music sheet. The sources can be set to any CSS compatible URL which can be passed into `url()`. See https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src#url +If you customize the SmuFL font used in alphaTab, you will also need to provide +the respective SMuFL Metadata information to alphaTab. +Set the metadata via {"fillFromSmufl"} on the rendering resources. + 
{"smuflFontSources"}{":"}{" "}{"Map"}{"<"}{"FontFileFormat"}{","}{" "}{"string"}{">"}{" "}{"|"}{" "}{"null"}{" "}{"="}{" "}{"Bravura files located at {\"fontDirectory\"} ."}{";"}
diff --git a/docs/reference/settings/display/effectbandpaddingbottom.mdx b/docs/reference/settings/display/effectbandpaddingbottom.mdx new file mode 100644 index 0000000..b238c85 --- /dev/null +++ b/docs/reference/settings/display/effectbandpaddingbottom.mdx @@ -0,0 +1,37 @@ +--- +title: display.effectBandPaddingBottom +description: "The padding between individual effect bands." +sidebar_custom_props: + jsOnParent: true + category: Display + since: 1.7.0 +--- + +import { ParameterTable, ParameterRow } from '@site/src/components/ParameterTable'; +import CodeBlock from '@theme/CodeBlock'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import { CodeBadge } from '@site/src/components/CodeBadge'; +import { SinceBadge } from '@site/src/components/SinceBadge'; +import DynHeading from '@site/src/components/DynHeading'; +import Link from '@docusaurus/Link'; + +import { SettingsHeader } from '@site/src/components/SettingsHeader'; + + + +### Description +The padding between individual effect bands. + + + +
{"effectBandPaddingBottom"}{":"}{" "}{"number"}{" "}{"="}{" "}{"2"}{";"}
+ + +
{"double"}{" "}{"EffectBandPaddingBottom"}{" "}{"{"}{" "}{"get"}{";"}{" "}{"set"}{";"}{" "}{"}"}{" "}{"="}{" "}{"2"}
+ + +
{"var"}{" "}{"effectBandPaddingBottom"}{":"}{" "}{"Double"}{" "}{"="}{" "}{"2"}
+ + + diff --git a/docs/reference/settings/exporter/comments.mdx b/docs/reference/settings/exporter/comments.mdx new file mode 100644 index 0000000..235173c --- /dev/null +++ b/docs/reference/settings/exporter/comments.mdx @@ -0,0 +1,36 @@ +--- +title: exporter.comments +description: "Whether to write extended comments into the exported file (e.g. to in alphaTex to mark where certain metadata or bars starts)" +sidebar_custom_props: + category: Exporter + since: 1.7.0 +--- + +import { ParameterTable, ParameterRow } from '@site/src/components/ParameterTable'; +import CodeBlock from '@theme/CodeBlock'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import { CodeBadge } from '@site/src/components/CodeBadge'; +import { SinceBadge } from '@site/src/components/SinceBadge'; +import DynHeading from '@site/src/components/DynHeading'; +import Link from '@docusaurus/Link'; + +import { SettingsHeader } from '@site/src/components/SettingsHeader'; + + + +### Description +Whether to write extended comments into the exported file (e.g. to in alphaTex to mark where certain metadata or bars starts) + + + +
{"comments"}{":"}{" "}{"boolean"}{" "}{"="}{" "}{"false"}{";"}
+ + +
{"bool"}{" "}{"Comments"}{" "}{"{"}{" "}{"get"}{";"}{" "}{"set"}{";"}{" "}{"}"}{" "}{"="}{" "}{"false"}
+ + +
{"var"}{" "}{"comments"}{":"}{" "}{"Boolean"}{" "}{"="}{" "}{"false"}
+ + + diff --git a/docs/reference/settings/exporter/indent.mdx b/docs/reference/settings/exporter/indent.mdx new file mode 100644 index 0000000..7c81c80 --- /dev/null +++ b/docs/reference/settings/exporter/indent.mdx @@ -0,0 +1,37 @@ +--- +title: exporter.indent +description: "How many characters should be indented on formatted outputs. If set to negative values" +sidebar_custom_props: + category: Exporter + since: 1.7.0 +--- + +import { ParameterTable, ParameterRow } from '@site/src/components/ParameterTable'; +import CodeBlock from '@theme/CodeBlock'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import { CodeBadge } from '@site/src/components/CodeBadge'; +import { SinceBadge } from '@site/src/components/SinceBadge'; +import DynHeading from '@site/src/components/DynHeading'; +import Link from '@docusaurus/Link'; + +import { SettingsHeader } from '@site/src/components/SettingsHeader'; + + + +### Description +How many characters should be indented on formatted outputs. If set to negative values +formatted outputs are disabled. + + + +
{"indent"}{":"}{" "}{"number"}{" "}{"="}{" "}{"2"}{";"}
+ + +
{"double"}{" "}{"Indent"}{" "}{"{"}{" "}{"get"}{";"}{" "}{"set"}{";"}{" "}{"}"}{" "}{"="}{" "}{"2"}
+ + +
{"var"}{" "}{"indent"}{":"}{" "}{"Double"}{" "}{"="}{" "}{"2"}
+ + + diff --git a/package-lock.json b/package-lock.json index 9c218f7..d12d41b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -8,7 +8,7 @@ "name": "alphatab-website", "version": "0.0.0", "dependencies": { - "@coderline/alphatab": "^1.6.0-alpha.1416", + "@coderline/alphatab": "^1.7.0-alpha.1515", "@docusaurus/core": "^3.7.0", "@docusaurus/preset-classic": "^3.7.0", "@docusaurus/theme-mermaid": "^3.7.0", @@ -1919,9 +1919,9 @@ "integrity": "sha512-YslZMgtJUyuMbZ+aKvfF3x1f5liK4mWNxghFRv7jqRR9C3R3fAOGTTKvxXDa2Y1s9zSbcpuO0cAxDYsc9SrXoQ==" }, "node_modules/@coderline/alphatab": { - "version": "1.6.0-alpha.1416", - "resolved": "https://registry.npmjs.org/@coderline/alphatab/-/alphatab-1.6.0-alpha.1416.tgz", - "integrity": "sha512-bIACxHyaTAnxtzz5I6Kr3a9LR6VLpvhm/o8GiZZeDc6wVtLEz+0a9sKCRBepSfz0+HVi09YzDMvhL9vEQrEbcw==", + "version": "1.7.0-alpha.1515", + "resolved": "https://registry.npmjs.org/@coderline/alphatab/-/alphatab-1.7.0-alpha.1515.tgz", + "integrity": "sha512-pJAnvSXiz53bEzYRM6K5ZUJPs0GIgX9Z4bX3uCNhPQeHbTJoG9f+OUTcEDg3mBnChTiyvJLUGTtn3XDAp66PIw==", "engines": { "node": ">=6.0.0" } diff --git a/package.json b/package.json index ea739f3..46db5c6 100644 --- a/package.json +++ b/package.json @@ -16,7 +16,7 @@ "generate-alphatabdoc": "tsx scripts/generate-alphatabdoc.mts" }, "dependencies": { - "@coderline/alphatab": "^1.6.0-alpha.1416", + "@coderline/alphatab": "^1.7.0-alpha.1515", "@docusaurus/core": "^3.7.0", "@docusaurus/preset-classic": "^3.7.0", "@docusaurus/theme-mermaid": "^3.7.0", diff --git a/scripts/generate-common.mts b/scripts/generate-common.mts index 4f8acd4..82b96a0 100644 --- a/scripts/generate-common.mts +++ b/scripts/generate-common.mts @@ -454,11 +454,11 @@ function tryGetSettingsUrl( .name!.getText() .toLowerCase()}/${symbol.name.toLowerCase()}`; } else { - cconsole.warn( - "Could not find a property of type ", - parentSymbol.name, - " in Settings" - ); + // cconsole.warn( + // "Could not find a property of type ", + // parentSymbol.name, + // " in Settings" + // ); return undefined; } } diff --git a/src/components/ReferenceTable/index.tsx b/src/components/ReferenceTable/index.tsx index af22459..620cc79 100644 --- a/src/components/ReferenceTable/index.tsx +++ b/src/components/ReferenceTable/index.tsx @@ -8,6 +8,7 @@ import { } from "@docusaurus/plugin-content-docs"; import { useDocById } from "@docusaurus/plugin-content-docs/client"; import { MarkdownString } from "../MarkdownString"; +import { useLocation } from "@docusaurus/router"; function buildPropertyUrl(property: Page) { let url = ""; @@ -24,12 +25,12 @@ type ReferenceRowProps = { property: Page; showJson: boolean }; const ReferenceRow: React.FC = ({ property, showJson }) => { const { mainName, javaScriptOnly } = buildNames(property); - + return ( - + @@ -70,7 +71,7 @@ const ReferenceCategory: React.FC = ({ return ( <> - {name} + {name} {rows} @@ -103,7 +104,7 @@ export const ReferenceTable: React.FC = ({ const existingKeys = new Map(); const pages: { key: string; items: Page[] }[] = []; for (const page of allPages) { - if(page.type === "link" && page.docId?.startsWith('_') === true) { + if (page.type === "link" && page.docId?.startsWith('_') === true) { continue; } @@ -131,6 +132,20 @@ export const ReferenceTable: React.FC = ({ /> )); + const { hash } = useLocation(); + useEffect(() => { + const id = hash.replace('#', ''); + const element = document.getElementById(id); + if (element) { + setTimeout(() => { + element.scrollIntoView({ + behavior: 'auto', + block: 'center', + }); + }, 100); + } + }, []); + return (