From 9b55ac3f076ce169a0cb7cb9e2eab67f5c1b05db Mon Sep 17 00:00:00 2001 From: Danielku15 Date: Wed, 12 Feb 2025 21:10:48 +0100 Subject: [PATCH 1/6] docs: Add pages for file format support --- docs/formats/capella.mdx | 18 ++++++++++++ docs/formats/guitar-pro-3-5.mdx | 16 +++++++++++ docs/formats/guitar-pro-6.mdx | 23 +++++++++++++++ docs/formats/guitar-pro-7-8.mdx | 24 ++++++++++++++++ docs/formats/musicxml.mdx | 22 ++++++++++++++ sidebars.ts | 51 ++++++++++++++++++++++++--------- 6 files changed, 141 insertions(+), 13 deletions(-) create mode 100644 docs/formats/capella.mdx create mode 100644 docs/formats/guitar-pro-3-5.mdx create mode 100644 docs/formats/guitar-pro-6.mdx create mode 100644 docs/formats/guitar-pro-7-8.mdx create mode 100644 docs/formats/musicxml.mdx diff --git a/docs/formats/capella.mdx b/docs/formats/capella.mdx new file mode 100644 index 0000000..719c649 --- /dev/null +++ b/docs/formats/capella.mdx @@ -0,0 +1,18 @@ +--- +title: Capella/CapXML (.capx) +description: The open file format of Capella. +--- + +Capella is a music notation software developed by the German company capella-software AG. +> https://www.guitar-pro.com/ + +Older versions of Capella had binary formats. alphaTab is only compatible with the XML based formats. +Capella files are Zip archives containing one single `score.xml` file following the [CapXML schema](https://www.capella.de/CapXML/). + +**Compatibility Level:** Only very basic support, not well tested + +Capella describes a lot of notation elements rather visually than semantically requiring alphaTab to make a best-guess on which exact beats/notes what elements should be applied. + +| Feature | Reading and Data Model | Rendering | Audio Generation | alphaTex | +|---------|------------------------|-----------|------------------|----------| +| | | | | | \ No newline at end of file diff --git a/docs/formats/guitar-pro-3-5.mdx b/docs/formats/guitar-pro-3-5.mdx new file mode 100644 index 0000000..856bece --- /dev/null +++ b/docs/formats/guitar-pro-3-5.mdx @@ -0,0 +1,16 @@ +--- +title: Guitar Pro 3-5 (.gp3, .gp4, .gp5) +description: The proprietary file format of the older Arobas Guitar Pro versions 3 to 5. +--- + +> Guitar Pro is a software program available on Windows and Mac OS that allows all musicians to read, write and share their tablatures. The world leader in tablature editing, Guitar Pro has been downloaded over 15 million times worldwide since 1997. +> https://www.guitar-pro.com/ + +Up to version 5, Guitar Pro was using a proprietary file format encoded in a binary structure. Arobas Music once released a documentation of version 4. +With this as base, any further format details have been manually reverse-engineered using test files. + +**Compatibility Level:** Mature and well tested + +| Feature | Reading and Data Model | Rendering | Audio Generation | alphaTex | +|---------|------------------------|-----------|------------------|----------| +| | | | | | \ No newline at end of file diff --git a/docs/formats/guitar-pro-6.mdx b/docs/formats/guitar-pro-6.mdx new file mode 100644 index 0000000..c6a3fd3 --- /dev/null +++ b/docs/formats/guitar-pro-6.mdx @@ -0,0 +1,23 @@ +--- +title: Guitar Pro 6 (.gpx) +description: The proprietary file format of the older Arobas Guitar Pro version 6. +--- + +> Guitar Pro is a software program available on Windows and Mac OS that allows all musicians to read, write and share their tablatures. The world leader in tablature editing, Guitar Pro has been downloaded over 15 million times worldwide since 1997. +> https://www.guitar-pro.com/ + +In version 6, Guitar Pro changed to a XML based file format. The GPX file itself is a custom proprierary container format similar to Zip holding multiple files: + +* `score.gpif` - The main XML structure representing the music notation. +* `misc.xml`- An auxiliary XML file holding some display information. +* `BinaryStylesheet` - A binary file holding key-value pairs with various settings around the display of music notation (File > Stylesheet in Guitar Pro). +* `PartConfiguration` - A binary file holding information on what tracks and staves to show in single and multi-track views. +* `LayoutConfiguration` - A binary file holding information on what layout to use for displaying music sheets (e.g. zoom level) + +Luckily when Guitar Pro 6 was released, the author of the format explained to the community how the encoding works. + +**Compatibility Level:** Mature and well tested + +| Feature | Reading and Data Model | Rendering | Audio Generation | alphaTex | +|---------|------------------------|-----------|------------------|----------| +| | | | | | \ No newline at end of file diff --git a/docs/formats/guitar-pro-7-8.mdx b/docs/formats/guitar-pro-7-8.mdx new file mode 100644 index 0000000..8f4c28a --- /dev/null +++ b/docs/formats/guitar-pro-7-8.mdx @@ -0,0 +1,24 @@ +--- +title: Guitar Pro 7-8 (.gp) +description: The proprietary file format of the current Arobas Guitar Pro version 7-8. +--- + +> Guitar Pro is a software program available on Windows and Mac OS that allows all musicians to read, write and share their tablatures. The world leader in tablature editing, Guitar Pro has been downloaded over 15 million times worldwide since 1997. +> https://www.guitar-pro.com/ + +In version 7, Guitar Pro changed to use a zip based file archive format. The zip contains similar files like Guitar Pro 6 but also additional ones: + +* `VERSION` - A file holding version information about the archive. +* `Content/score.gpif` - The main XML structure representing the music notation. +* `Content/Preferences.json`- A JSON file holding some settings influencing Guitar Pro itself (e.g. to activate the speed trainer). +* `BinaryStylesheet` - A binary file holding key-value pairs with various settings around the display of music notation (File > Stylesheet in Guitar Pro). +* `PartConfiguration` - A binary file holding information on what tracks and staves to show in single and multi-track views. +* `LayoutConfiguration` - A binary file holding information on what layout to use for displaying music sheets (e.g. zoom level) + +The `score.gpif` is the same as in Guitar Pro 6 but evovling with new features since then. + +**Compatibility Level:** Mature and well tested + +| Feature | Reading and Data Model | Rendering | Audio Generation | alphaTex | +|---------|------------------------|-----------|------------------|----------| +| | | | | | diff --git a/docs/formats/musicxml.mdx b/docs/formats/musicxml.mdx new file mode 100644 index 0000000..2448901 --- /dev/null +++ b/docs/formats/musicxml.mdx @@ -0,0 +1,22 @@ +--- +title: MusicXML (.musicxml) +description: The open file format format for exchanging music notation. +--- + +> The standard open format for exchanging digital sheet music. +> +> MusicXML was designed from the ground up for sharing sheet music files between applications, and for archiving sheet music files for use in the future. You can count on MusicXML files being readable and usable by a wide range of music notation applications, now and in the future. MusicXML complements the native file formats used by Finale and other programs, which are designed for rapid, interactive use. +> https://www.musicxml.com/ + + +**Compatibility Level:** Basic, good test coverage. + +MusicXML is a very complex format and often also describes things rather visually than semantically. The format itself is very mature and supports a vast amount of +notation elements to be described. This also makes it quite complex to handle as applications might have to deal with elements which are not supported by the application itself. + +Additionally the different applications supporting MusicXML have their own slight dialects and expectations to where elements are placed. +This can easily cause visual discrepancies when exchanging files across applications. + +| Feature | Reading and Data Model | Rendering | Audio Generation | alphaTex | +|---------|------------------------|-----------|------------------|----------| +| | | | | | \ No newline at end of file diff --git a/sidebars.ts b/sidebars.ts index 92588c6..087bb93 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -1,4 +1,4 @@ -import type { SidebarsConfig } from '@docusaurus/plugin-content-docs'; +import type { SidebarsConfig } from "@docusaurus/plugin-content-docs"; const sidebars: SidebarsConfig = { docs: { @@ -146,18 +146,43 @@ const sidebars: SidebarsConfig = { "alphatex/percussion", ], }, - showcase: { - Showcase: [ - "showcase/introduction", - "showcase/general", - "showcase/layouts", - "showcase/music-notation", - "showcase/guitar-tabs", - "showcase/special-tracks", - "showcase/special-notes", - "showcase/effects", - ], - }, + showcase: [ + { + type: "category", + label: "Showcase", + link: { + type: "doc", + id: "showcase/introduction" + }, + items: [ + "showcase/introduction", + "showcase/general", + "showcase/layouts", + "showcase/music-notation", + "showcase/guitar-tabs", + "showcase/special-tracks", + "showcase/special-notes", + "showcase/effects", + ], + }, + { + type: "category", + label: "Formats", + link: { + type: "generated-index", + title: "Introduction", + description: + "These pages provide an insight on what the input file formats alphaTab supports and the compatibility for rendering and expressing the same in alphaTex.", + }, + items: [ + "formats/guitar-pro-7-8", + "formats/guitar-pro-6", + "formats/guitar-pro-3-5", + "formats/musicxml", + "formats/capella", + ], + }, + ], }; module.exports = sidebars; From fd9e95c846030a470388427af23435883786df0f Mon Sep 17 00:00:00 2001 From: Danielku15 Date: Wed, 12 Feb 2025 23:58:17 +0100 Subject: [PATCH 2/6] docs: Add GP3-GP5 feature table --- docs/alphatex/lyrics.mdx | 15 + docs/formats/guitar-pro-3-5.mdx | 491 +++++++++++++++++- package-lock.json | 41 ++ package.json | 1 + .../FileFormatFeatureTable/index.tsx | 268 ++++++++++ .../FileFormatFeatureTable/styles.module.scss | 11 + src/css/custom.scss | 5 +- 7 files changed, 828 insertions(+), 4 deletions(-) create mode 100644 docs/alphatex/lyrics.mdx create mode 100644 src/components/FileFormatFeatureTable/index.tsx create mode 100644 src/components/FileFormatFeatureTable/styles.module.scss diff --git a/docs/alphatex/lyrics.mdx b/docs/alphatex/lyrics.mdx new file mode 100644 index 0000000..3791c94 --- /dev/null +++ b/docs/alphatex/lyrics.mdx @@ -0,0 +1,15 @@ +--- +title: Lyrics +--- + +TODO: Document Lyrics + +Staff Meta level meta: + +`\lyrics "Text"` + +`\lyrics StartBar "Text"` + +Spaces split word syllables, +Plus for merge syllables +`[..]` comments \ No newline at end of file diff --git a/docs/formats/guitar-pro-3-5.mdx b/docs/formats/guitar-pro-3-5.mdx index 856bece..2a046f5 100644 --- a/docs/formats/guitar-pro-3-5.mdx +++ b/docs/formats/guitar-pro-3-5.mdx @@ -3,6 +3,8 @@ title: Guitar Pro 3-5 (.gp3, .gp4, .gp5) description: The proprietary file format of the older Arobas Guitar Pro versions 3 to 5. --- +## Introduction + > Guitar Pro is a software program available on Windows and Mac OS that allows all musicians to read, write and share their tablatures. The world leader in tablature editing, Guitar Pro has been downloaded over 15 million times worldwide since 1997. > https://www.guitar-pro.com/ @@ -11,6 +13,489 @@ With this as base, any further format details have been manually reverse-enginee **Compatibility Level:** Mature and well tested -| Feature | Reading and Data Model | Rendering | Audio Generation | alphaTex | -|---------|------------------------|-----------|------------------|----------| -| | | | | | \ No newline at end of file +## Feature Table + +import { FileFormatFeatureTable, FileFormatFeatureGroup, FileFormatFeatureRow, FeatureStatus } from '@site/src/components/FileFormatFeatureTable' + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/package-lock.json b/package-lock.json index 78e4f32..48a7cde 100644 --- a/package-lock.json +++ b/package-lock.json @@ -22,6 +22,7 @@ "prism-react-renderer": "^2.3.1", "react": "^18.3.1", "react-dom": "^18.3.1", + "react-tooltip": "^5.28.0", "webpack": "^5.94.0" }, "devDependencies": { @@ -2877,6 +2878,28 @@ "node": ">=18.0" } }, + "node_modules/@floating-ui/core": { + "version": "1.6.9", + "resolved": "https://registry.npmjs.org/@floating-ui/core/-/core-1.6.9.tgz", + "integrity": "sha512-uMXCuQ3BItDUbAMhIXw7UPXRfAlOAvZzdK9BWpE60MCn+Svt3aLn9jsPTi/WNGlRUu2uI0v5S7JiIUsbsvh3fw==", + "dependencies": { + "@floating-ui/utils": "^0.2.9" + } + }, + "node_modules/@floating-ui/dom": { + "version": "1.6.13", + "resolved": "https://registry.npmjs.org/@floating-ui/dom/-/dom-1.6.13.tgz", + "integrity": "sha512-umqzocjDgNRGTuO7Q8CU32dkHkECqI8ZdMZ5Swb6QAM0t5rnlrN3lGo1hdpscRd3WS8T6DKYK4ephgIH9iRh3w==", + "dependencies": { + "@floating-ui/core": "^1.6.0", + "@floating-ui/utils": "^0.2.9" + } + }, + "node_modules/@floating-ui/utils": { + "version": "0.2.9", + "resolved": "https://registry.npmjs.org/@floating-ui/utils/-/utils-0.2.9.tgz", + "integrity": "sha512-MDWhGtE+eHw5JW7lq4qhc5yRLS11ERl1c7Z6Xd0a58DozHES6EnNNwUWbMiG4J9Cgj053Bhk8zvlhFYKVhULwg==" + }, "node_modules/@fortawesome/fontawesome-common-types": { "version": "6.5.2", "resolved": "https://registry.npmjs.org/@fortawesome/fontawesome-common-types/-/fontawesome-common-types-6.5.2.tgz", @@ -4884,6 +4907,11 @@ "node": ">=8" } }, + "node_modules/classnames": { + "version": "2.5.1", + "resolved": "https://registry.npmjs.org/classnames/-/classnames-2.5.1.tgz", + "integrity": "sha512-saHYOzhIQs6wy2sVxTM6bUDsQO4F50V9RQ22qBpEdCW+I+/Wmke2HOl6lS6dTpdxVhb88/I6+Hs+438c3lfUow==" + }, "node_modules/clean-css": { "version": "5.3.3", "resolved": "https://registry.npmjs.org/clean-css/-/clean-css-5.3.3.tgz", @@ -14083,6 +14111,19 @@ "react": ">=15" } }, + "node_modules/react-tooltip": { + "version": "5.28.0", + "resolved": "https://registry.npmjs.org/react-tooltip/-/react-tooltip-5.28.0.tgz", + "integrity": "sha512-R5cO3JPPXk6FRbBHMO0rI9nkUG/JKfalBSQfZedZYzmqaZQgq7GLzF8vcCWx6IhUCKg0yPqJhXIzmIO5ff15xg==", + "dependencies": { + "@floating-ui/dom": "^1.6.1", + "classnames": "^2.3.0" + }, + "peerDependencies": { + "react": ">=16.14.0", + "react-dom": ">=16.14.0" + } + }, "node_modules/readable-stream": { "version": "3.6.2", "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.2.tgz", diff --git a/package.json b/package.json index 2797b30..ec8f0fc 100644 --- a/package.json +++ b/package.json @@ -29,6 +29,7 @@ "prism-react-renderer": "^2.3.1", "react": "^18.3.1", "react-dom": "^18.3.1", + "react-tooltip": "^5.28.0", "webpack": "^5.94.0" }, "devDependencies": { diff --git a/src/components/FileFormatFeatureTable/index.tsx b/src/components/FileFormatFeatureTable/index.tsx new file mode 100644 index 0000000..5091a7a --- /dev/null +++ b/src/components/FileFormatFeatureTable/index.tsx @@ -0,0 +1,268 @@ +import React from "react"; +import { SinceBadge } from "../SinceBadge"; +import Details from "@theme/Details"; +import { Tooltip } from "react-tooltip"; +import ReactDOMServer from "react-dom/server"; +import styles from "./styles.module.scss"; + +export enum FeatureStatus { + Supported, + Partial, + NotSupported, + Ignored, + Unspecified, +} + +class FeatureStatusDisplay extends React.Component<{ status: FeatureStatus }> { + public render() { + switch (this.props.status) { + case FeatureStatus.Supported: + return <>✅ Supported; + case FeatureStatus.Partial: + return <>⚠️ Partial; + case FeatureStatus.NotSupported: + return <>❌ Not Supported; + case FeatureStatus.Ignored: + return <>✅ Ignored; + case FeatureStatus.Unspecified: + return <>; + } + return <>; + } +} + +type FeatureStatusDefinitionFull = { + status: FeatureStatus; + tooltip?: string; + since?: string; +}; + +export class FileFormatFeatureCell extends React.Component<{ + status?: FeatureStatusDefinitionFull; +}> { + public render() { + if (!this.props.status) { + return <>; + } + + const tooltip = + this.props.status.since || this.props.status.tooltip + ? ReactDOMServer.renderToStaticMarkup( + <> + {" "} + {this.props.status.tooltip} + + ) + : ""; + + const classNames = ["feature-status-cell", styles.noWrap]; + if (tooltip) { + classNames.push(styles.hasTooltip); + } + + return ( + <> + + + + + ); + } +} + +export class FileFormatFeatureGroup extends React.Component<{ + title: string; + children: React.ReactNode; +}> { + public render() { + return ( + <> + + + {this.props.title} + + + + + + + + {this.props.children} + + ); + } +} + +type FeatureStatusDefinition = + | FeatureStatus + | [FeatureStatus] + | [FeatureStatus, string] + | [FeatureStatus, string, string] + | FeatureStatusDefinitionFull; + +function toFeatureStatusDefinitionFull( + definition?: FeatureStatusDefinition +): FeatureStatusDefinitionFull | undefined { + if (typeof definition === "undefined") { + return undefined; + } + + if (typeof definition === "number") { + return { + status: definition, + }; + } + + if (Array.isArray(definition)) { + if (definition.length === 1) { + return { + status: definition[0] as number, + }; + } else if (definition.length === 2) { + return { + status: definition[0] as number, + since: definition[1] as string, + }; + } else if (definition.length === 3) { + return { + status: definition[0] as number, + since: definition[1] as string, + tooltip: definition[2] as string, + }; + } + } + + if ("status" in definition) { + return definition; + } + + throw new Error("Invalid status definition"); +} + +export class FileFormatFeatureRow extends React.Component<{ + feature: string; + + model?: FeatureStatusDefinition; + reading?: FeatureStatusDefinition; + render?: FeatureStatusDefinition; + audio?: FeatureStatusDefinition; + tex?: FeatureStatusDefinition; +}> { + public render() { + return ( + + {this.props.feature} + + + + + + + + + + + + + + + + + ); + } +} + +export class FileFormatFeatureTable extends React.Component<{ + children: React.ReactNode; +}> { + public render() { + return ( + <> +
+

+ The following table describes the support of the different features + of the input format. +

+

+ Columns +

+
    +
  • Feature: The related feature
    • +
  • + Data Model: Whether alphaTab supports storing this information in + its own data model (e.g. from other formats). +
    • +
  • + Reading: Whether alphaTab can read this information from the file + format. +
    • +
  • + Rendering: Whether alphaTab can display the information in the + music sheet when rendered (display might differ from reference + software). +
    • +
  • + Audio: Whether alphaTab can generate audio information for this + feature. +
    • +
  • + alphaTex: Whether this feature is supported when describing music + notation with alphaTex. +
    • +
+

+ Values +

+
    +
  • + - The + feature is fully supported by alphaTab. +
    • +
  • + - The + feature is partially supported by alphaTab, hover the item to see + more details. +
    • +
  • + - The + feature is not supported by alphaTab. +
    • +
  • + - The + feature is ignored from the input format because it is considered + not relevant for display or playback. This is opinionated based on the feature set in alphaTab, + open a feature request if you need it. +
    • +
+
+ + + + + + + + + + + + + {this.props.children} +
FeatureData ModelReadingRenderingAudioalphaTex
+ + ); + } +} diff --git a/src/components/FileFormatFeatureTable/styles.module.scss b/src/components/FileFormatFeatureTable/styles.module.scss new file mode 100644 index 0000000..b5a6254 --- /dev/null +++ b/src/components/FileFormatFeatureTable/styles.module.scss @@ -0,0 +1,11 @@ +.noWrap { + white-space: nowrap; +} + +.hasTooltip { + text-decoration: underline; + text-decoration-style: dotted; + text-decoration-line: underline; + text-decoration-thickness: 1px; + cursor: help; +} \ No newline at end of file diff --git a/src/css/custom.scss b/src/css/custom.scss index 9c82bb8..03445d2 100644 --- a/src/css/custom.scss +++ b/src/css/custom.scss @@ -77,4 +77,7 @@ li.reference-item ul { background: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E") no-repeat; margin-right: 0.25rem; -} \ No newline at end of file +} + +@import 'react-tooltip/dist/react-tooltip.css' + From 8a1f9ec9f752cf897ace79b2f563a5336309e77b Mon Sep 17 00:00:00 2001 From: Danielku15 Date: Thu, 13 Feb 2025 01:27:36 +0100 Subject: [PATCH 3/6] docs: Document Guitar Pro compatibiltiy --- docs/formats/guitar-pro-3-5.mdx | 58 +- docs/formats/guitar-pro-6.mdx | 623 ++++++++++++++- docs/formats/guitar-pro-7-8.mdx | 24 - docs/formats/guitar-pro-7.mdx | 691 +++++++++++++++++ docs/formats/guitar-pro-8.mdx | 727 ++++++++++++++++++ sidebars.ts | 3 +- .../FileFormatFeatureTable/index.tsx | 7 +- .../FileFormatFeatureTable/styles.module.scss | 4 + 8 files changed, 2095 insertions(+), 42 deletions(-) delete mode 100644 docs/formats/guitar-pro-7-8.mdx create mode 100644 docs/formats/guitar-pro-7.mdx create mode 100644 docs/formats/guitar-pro-8.mdx diff --git a/docs/formats/guitar-pro-3-5.mdx b/docs/formats/guitar-pro-3-5.mdx index 2a046f5..b00669e 100644 --- a/docs/formats/guitar-pro-3-5.mdx +++ b/docs/formats/guitar-pro-3-5.mdx @@ -32,6 +32,37 @@ import { FileFormatFeatureTable, FileFormatFeatureGroup, FileFormatFeatureRow, F render={[FeatureStatus.Supported]} audio={[FeatureStatus.Ignored]} tex={[FeatureStatus.Supported]} /> + + + + + + @@ -56,14 +87,14 @@ import { FileFormatFeatureTable, FileFormatFeatureGroup, FileFormatFeatureRow, F audio={[FeatureStatus.Supported]} tex={[FeatureStatus.Supported]} /> @@ -157,10 +188,9 @@ import { FileFormatFeatureTable, FileFormatFeatureGroup, FileFormatFeatureRow, F render={[FeatureStatus.Ignored]} audio={[FeatureStatus.NotSupported]} tex={[FeatureStatus.NotSupported]} /> - - + + tex={[FeatureStatus.NotSupported]} /> + - - + Guitar Pro is a software program available on Windows and Mac OS that allows all musicians to read, write and share their tablatures. The world leader in tablature editing, Guitar Pro has been downloaded over 15 million times worldwide since 1997. > https://www.guitar-pro.com/ @@ -18,6 +20,621 @@ Luckily when Guitar Pro 6 was released, the author of the format explained to th **Compatibility Level:** Mature and well tested -| Feature | Reading and Data Model | Rendering | Audio Generation | alphaTex | -|---------|------------------------|-----------|------------------|----------| -| | | | | | \ No newline at end of file +## Feature Table + +import { FileFormatFeatureTable, FileFormatFeatureGroup, FileFormatFeatureRow, FeatureStatus } from '@site/src/components/FileFormatFeatureTable' + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/formats/guitar-pro-7-8.mdx b/docs/formats/guitar-pro-7-8.mdx deleted file mode 100644 index 8f4c28a..0000000 --- a/docs/formats/guitar-pro-7-8.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Guitar Pro 7-8 (.gp) -description: The proprietary file format of the current Arobas Guitar Pro version 7-8. ---- - -> Guitar Pro is a software program available on Windows and Mac OS that allows all musicians to read, write and share their tablatures. The world leader in tablature editing, Guitar Pro has been downloaded over 15 million times worldwide since 1997. -> https://www.guitar-pro.com/ - -In version 7, Guitar Pro changed to use a zip based file archive format. The zip contains similar files like Guitar Pro 6 but also additional ones: - -* `VERSION` - A file holding version information about the archive. -* `Content/score.gpif` - The main XML structure representing the music notation. -* `Content/Preferences.json`- A JSON file holding some settings influencing Guitar Pro itself (e.g. to activate the speed trainer). -* `BinaryStylesheet` - A binary file holding key-value pairs with various settings around the display of music notation (File > Stylesheet in Guitar Pro). -* `PartConfiguration` - A binary file holding information on what tracks and staves to show in single and multi-track views. -* `LayoutConfiguration` - A binary file holding information on what layout to use for displaying music sheets (e.g. zoom level) - -The `score.gpif` is the same as in Guitar Pro 6 but evovling with new features since then. - -**Compatibility Level:** Mature and well tested - -| Feature | Reading and Data Model | Rendering | Audio Generation | alphaTex | -|---------|------------------------|-----------|------------------|----------| -| | | | | | diff --git a/docs/formats/guitar-pro-7.mdx b/docs/formats/guitar-pro-7.mdx new file mode 100644 index 0000000..f922186 --- /dev/null +++ b/docs/formats/guitar-pro-7.mdx @@ -0,0 +1,691 @@ +--- +title: Guitar Pro 7 (.gp) +description: The proprietary file format of the current Arobas Guitar Pro version 7. +--- + +## Introduction + +> Guitar Pro is a software program available on Windows and Mac OS that allows all musicians to read, write and share their tablatures. The world leader in tablature editing, Guitar Pro has been downloaded over 15 million times worldwide since 1997. +> https://www.guitar-pro.com/ + +In version 7, Guitar Pro changed to use a zip based file archive format. The zip contains similar files like Guitar Pro 6 but also additional ones: + +* `VERSION` - A file holding version information about the archive. +* `Content/score.gpif` - The main XML structure representing the music notation. +* `Content/Preferences.json`- A JSON file holding some settings influencing Guitar Pro itself (e.g. to activate the speed trainer). +* `BinaryStylesheet` - A binary file holding key-value pairs with various settings around the display of music notation (File > Stylesheet in Guitar Pro). +* `PartConfiguration` - A binary file holding information on what tracks and staves to show in single and multi-track views. +* `LayoutConfiguration` - A binary file holding information on what layout to use for displaying music sheets (e.g. zoom level) + +The `score.gpif` is the same as in Guitar Pro 6 but evovling with new features since then. + +**Compatibility Level:** Mature and well tested + +## Feature Table + +import { FileFormatFeatureTable, FileFormatFeatureGroup, FileFormatFeatureRow, FeatureStatus } from '@site/src/components/FileFormatFeatureTable' + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/formats/guitar-pro-8.mdx b/docs/formats/guitar-pro-8.mdx new file mode 100644 index 0000000..ff2da9e --- /dev/null +++ b/docs/formats/guitar-pro-8.mdx @@ -0,0 +1,727 @@ +--- +title: Guitar Pro 8 (.gp) +description: The proprietary file format of the current Arobas Guitar Pro version 8. +--- + +## Introduction + +> Guitar Pro is a software program available on Windows and Mac OS that allows all musicians to read, write and share their tablatures. The world leader in tablature editing, Guitar Pro has been downloaded over 15 million times worldwide since 1997. +> https://www.guitar-pro.com/ + +The general file format of Guitar Pro 8 is the same as Guitar Pro 8 but with potentially additional files in the zip (e.g. for audio tracks) and with an extended `score.gpif` for new features. + +**Compatibility Level:** Mature and well tested (through GP7) + + +## Feature Table + +import { FileFormatFeatureTable, FileFormatFeatureGroup, FileFormatFeatureRow, FeatureStatus } from '@site/src/components/FileFormatFeatureTable' + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/sidebars.ts b/sidebars.ts index 087bb93..bea1e59 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -175,7 +175,8 @@ const sidebars: SidebarsConfig = { "These pages provide an insight on what the input file formats alphaTab supports and the compatibility for rendering and expressing the same in alphaTex.", }, items: [ - "formats/guitar-pro-7-8", + "formats/guitar-pro-8", + "formats/guitar-pro-7", "formats/guitar-pro-6", "formats/guitar-pro-3-5", "formats/musicxml", diff --git a/src/components/FileFormatFeatureTable/index.tsx b/src/components/FileFormatFeatureTable/index.tsx index 5091a7a..5a1735e 100644 --- a/src/components/FileFormatFeatureTable/index.tsx +++ b/src/components/FileFormatFeatureTable/index.tsx @@ -23,7 +23,7 @@ class FeatureStatusDisplay extends React.Component<{ status: FeatureStatus }> { case FeatureStatus.NotSupported: return <>❌ Not Supported; case FeatureStatus.Ignored: - return <>✅ Ignored; + return ✅ Ignored; case FeatureStatus.Unspecified: return <>; } @@ -144,6 +144,7 @@ function toFeatureStatusDefinitionFull( export class FileFormatFeatureRow extends React.Component<{ feature: string; + isNewFeature:boolean; model?: FeatureStatusDefinition; reading?: FeatureStatusDefinition; @@ -154,7 +155,7 @@ export class FileFormatFeatureRow extends React.Component<{ public render() { return ( - {this.props.feature} + {(this.props.isNewFeature ? "⭐ " : "") + this.props.feature} Columns

    -
  • Feature: The related feature
    • +
  • Feature: The related feature. If marked with ⭐ its a new or changed feature compared to the previous version of this format (e.g. a feature added in Guitar Pro 6)
  • Data Model: Whether alphaTab supports storing this information in its own data model (e.g. from other formats). diff --git a/src/components/FileFormatFeatureTable/styles.module.scss b/src/components/FileFormatFeatureTable/styles.module.scss index b5a6254..91d9b0f 100644 --- a/src/components/FileFormatFeatureTable/styles.module.scss +++ b/src/components/FileFormatFeatureTable/styles.module.scss @@ -8,4 +8,8 @@ text-decoration-line: underline; text-decoration-thickness: 1px; cursor: help; +} + +.ignored { + opacity: 0.5; } \ No newline at end of file From fd253c525e280ddedf0cb44dd204bc07054e91cc Mon Sep 17 00:00:00 2001 From: Danielku15 Date: Thu, 13 Feb 2025 01:48:28 +0100 Subject: [PATCH 4/6] docs: Add lyrics docs --- docs/alphatex/lyrics.mdx | 47 ++++++++++++++++++++++++++++++++++------ sidebars.ts | 1 + 2 files changed, 41 insertions(+), 7 deletions(-) diff --git a/docs/alphatex/lyrics.mdx b/docs/alphatex/lyrics.mdx index 3791c94..a2b6de2 100644 --- a/docs/alphatex/lyrics.mdx +++ b/docs/alphatex/lyrics.mdx @@ -2,14 +2,47 @@ title: Lyrics --- -TODO: Document Lyrics +The lyrics system of alphaTab is borrowed from Guitar Pro. For every track multiple "lines" of lyrics can be defined which can either start at the beginning or at a later bar. +The syllables of the procided lyrics are spread automatically across the beats of the track. Syllables are separated with spaces. +If multiple words/syllables should stay on the same beat the space can be replaced with a `+`. +Comments which should not be displayed can be put `[into brackets]`. -Staff Meta level meta: +To add lyrics to a track use the `\lyrics "Text"` or `\lyrics StartBar "Text"` metadata tag on track/staff level. -`\lyrics "Text"` +Here some samples: -`\lyrics StartBar "Text"` +import { AlphaTexSample } from '@site/src/components/AlphaTexSample'; -Spaces split word syllables, -Plus for merge syllables -`[..]` comments \ No newline at end of file +{` +\\title "With Lyrics" +\\instrument piano +. +\\lyrics "Do Re Mi Fa So La Ti" +C4 D4 E4 F4 | G4 A4 B4 r +`} + +{` +\\title "Combine Syllables (and empty beats)" +\\instrument piano +. +\\lyrics "Do+Do Mi+Mi" +C4 C4 E4 E4 +`} + +{` +\\title "Start Later" +\\instrument piano +. +\\lyrics 2 "Do Re Mi Fa So La Ti" +r r r r | r r r r | +C4 D4 E4 F4 | G4 A4 B4 r +`} + +{` +\\title "Comment" +\\subtitle "Useful when loading lyrics from a different source" +\\instrument piano +. +\\lyrics "[This is a comment]Do Re Mi Fa" +C4 D4 E4 F4 +`} \ No newline at end of file diff --git a/sidebars.ts b/sidebars.ts index bea1e59..ad13294 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -144,6 +144,7 @@ const sidebars: SidebarsConfig = { "alphatex/beat-effects", "alphatex/note-effects", "alphatex/percussion", + "alphatex/lyrics", ], }, showcase: [ From 69332a645959c589215ff6b93c675417de1e71ef Mon Sep 17 00:00:00 2001 From: Danielku15 Date: Thu, 13 Feb 2025 04:17:49 +0100 Subject: [PATCH 5/6] docs: document capella compatibility --- docs/formats/capella.mdx | 432 +++++++++++++++++- docs/formats/guitar-pro-3-5.mdx | 8 +- .../FileFormatFeatureTable/index.tsx | 124 ++++- .../FileFormatFeatureTable/styles.module.scss | 6 +- tsconfig.json | 3 +- 5 files changed, 550 insertions(+), 23 deletions(-) diff --git a/docs/formats/capella.mdx b/docs/formats/capella.mdx index 719c649..c8e67fd 100644 --- a/docs/formats/capella.mdx +++ b/docs/formats/capella.mdx @@ -3,16 +3,438 @@ title: Capella/CapXML (.capx) description: The open file format of Capella. --- +## Introduction + Capella is a music notation software developed by the German company capella-software AG. -> https://www.guitar-pro.com/ +https://www.capella.de Older versions of Capella had binary formats. alphaTab is only compatible with the XML based formats. Capella files are Zip archives containing one single `score.xml` file following the [CapXML schema](https://www.capella.de/CapXML/). **Compatibility Level:** Only very basic support, not well tested -Capella describes a lot of notation elements rather visually than semantically requiring alphaTab to make a best-guess on which exact beats/notes what elements should be applied. +Capella describes a lot of notation elements rather visually through "graphical objects" than semantically. +This requires alphaTab to make a best-guess on which exact beats/notes what elements should be applied. + +## Feature Table + +import { FileFormatFeatureTable, FileFormatFeatureGroup, FileFormatFeatureRow, FeatureStatus } from '@site/src/components/FileFormatFeatureTable' + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -| Feature | Reading and Data Model | Rendering | Audio Generation | alphaTex | -|---------|------------------------|-----------|------------------|----------| -| | | | | | \ No newline at end of file + + \ No newline at end of file diff --git a/docs/formats/guitar-pro-3-5.mdx b/docs/formats/guitar-pro-3-5.mdx index b00669e..8ed91d4 100644 --- a/docs/formats/guitar-pro-3-5.mdx +++ b/docs/formats/guitar-pro-3-5.mdx @@ -183,11 +183,11 @@ import { FileFormatFeatureTable, FileFormatFeatureGroup, FileFormatFeatureRow, F audio={[FeatureStatus.Supported]} tex={[FeatureStatus.NotSupported]} /> + audio={[FeatureStatus.Ignored]} + tex={[FeatureStatus.Ignored]} /> diff --git a/src/components/FileFormatFeatureTable/index.tsx b/src/components/FileFormatFeatureTable/index.tsx index 5a1735e..c00ba35 100644 --- a/src/components/FileFormatFeatureTable/index.tsx +++ b/src/components/FileFormatFeatureTable/index.tsx @@ -55,17 +55,14 @@ export class FileFormatFeatureCell extends React.Component<{ ) : ""; - const classNames = ["feature-status-cell", styles.noWrap]; + const classNames = ["feature-status-has-tooltip", styles.noWrap]; if (tooltip) { classNames.push(styles.hasTooltip); } return ( <> - + @@ -73,16 +70,73 @@ export class FileFormatFeatureCell extends React.Component<{ } } +function computeFeatureStatistics(node: React.ReactNode): { + totalFeatures: number; + supportedFeatures: number; + totalRelevantFeatures: number; + supportedRelevantFeatures: number; +} { + let featureRows: FileFormatFeatureRow[] = []; + collectChildren( + featureRows, + node, + FileFormatFeatureRow + ); + + let totalFeatures = featureRows.length; + let supportedFeatures = featureRows.filter((f) => { + const status = toFeatureStatusDefinitionFull(f.props.reading)?.status; + return ( + status === undefined || + status == FeatureStatus.Ignored || + status == FeatureStatus.Supported || + status == FeatureStatus.Unspecified + ); + }).length; + + const relevantFeatures = featureRows.filter( + (r) => + toFeatureStatusDefinitionFull(r.props.model)?.status !== + FeatureStatus.Ignored + ); + let totalRelevantFeatures = relevantFeatures.length; + let supportedRelevantFeatures = relevantFeatures.filter((f) => { + const status = toFeatureStatusDefinitionFull(f.props.reading)?.status; + return ( + status === undefined || + status == FeatureStatus.Ignored || + status == FeatureStatus.Supported || + status == FeatureStatus.Unspecified + ); + }).length; + + return { + totalFeatures, + supportedFeatures, + totalRelevantFeatures, + supportedRelevantFeatures, + }; +} + export class FileFormatFeatureGroup extends React.Component<{ title: string; children: React.ReactNode; }> { public render() { + const tooltip = ReactDOMServer.renderToStaticMarkup( + + ); + + const classNames = ["feature-status-has-tooltip", styles.noWrap]; + if (tooltip) { + classNames.push(styles.hasTooltip); + } + return ( <> - {this.props.title} + {this.props.title} @@ -142,9 +196,30 @@ function toFeatureStatusDefinitionFull( throw new Error("Invalid status definition"); } +export class FileFormatFeatureStatistics extends React.Component<{ + node: React.ReactNode; +}> { + public render() { + const statistics = computeFeatureStatistics(this.props.node); + return ( +

    + Number of total supported features:{" "} + {((statistics.supportedFeatures / statistics.totalFeatures) * 100) | 0}% + ({statistics.supportedFeatures}/{statistics.totalFeatures})
    + Number of relevant supported features:{" "} + {((statistics.supportedRelevantFeatures / + statistics.totalRelevantFeatures) * + 100) | + 0} + % ({statistics.supportedRelevantFeatures}/ + {statistics.totalRelevantFeatures})
    +

    + ); + } +} export class FileFormatFeatureRow extends React.Component<{ feature: string; - isNewFeature:boolean; + isNewFeature: boolean; model?: FeatureStatusDefinition; reading?: FeatureStatusDefinition; @@ -186,12 +261,28 @@ export class FileFormatFeatureRow extends React.Component<{ } } +function collectChildren(items: T[], node: React.ReactNode, type: any) { + if (typeof node === "object") { + // array + if (Symbol.iterator in node) { + for (const c of node as Iterable) { + collectChildren(items, c, type); + } + } else if (node.type === type) { + items.push(node as T); + } else if ("props" in node && "children" in node.props) { + collectChildren(items, node.props.children, type); + } + } +} + export class FileFormatFeatureTable extends React.Component<{ children: React.ReactNode; }> { public render() { return ( <> +

    The following table describes the support of the different features @@ -201,7 +292,11 @@ export class FileFormatFeatureTable extends React.Component<{ Columns

      -
    • Feature: The related feature. If marked with ⭐ its a new or changed feature compared to the previous version of this format (e.g. a feature added in Guitar Pro 6)
      • +
    • + Feature: The related feature. If marked with ⭐ its a new or + changed feature compared to the previous version of this format + (e.g. a feature added in Guitar Pro 6) +
    • Data Model: Whether alphaTab supports storing this information in its own data model (e.g. from other formats). @@ -244,13 +339,18 @@ export class FileFormatFeatureTable extends React.Component<{
    • - The feature is ignored from the input format because it is considered - not relevant for display or playback. This is opinionated based on the feature set in alphaTab, - open a feature request if you need it. + not relevant for display or playback. This is opinionated based on + the feature set in alphaTab, open a feature request if you need + it.
    - - + +
    diff --git a/src/components/FileFormatFeatureTable/styles.module.scss b/src/components/FileFormatFeatureTable/styles.module.scss index 91d9b0f..0c916c3 100644 --- a/src/components/FileFormatFeatureTable/styles.module.scss +++ b/src/components/FileFormatFeatureTable/styles.module.scss @@ -12,4 +12,8 @@ .ignored { opacity: 0.5; -} \ No newline at end of file +} + +.featureTable tbody tr td:nth-child(3) { + background-color: rgba(210, 231, 255, 0.5); +} \ No newline at end of file diff --git a/tsconfig.json b/tsconfig.json index 314eab8..9c8ecfc 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -2,6 +2,7 @@ // This file is not used in compilation. It is here just for a nice editor experience. "extends": "@docusaurus/tsconfig", "compilerOptions": { - "baseUrl": "." + "baseUrl": ".", + "downlevelIteration": true } } From d4e1ea7bb03c2221f40ecdcf259d078bd72e79fb Mon Sep 17 00:00:00 2001 From: Danielku15 Date: Thu, 13 Feb 2025 15:49:08 +0100 Subject: [PATCH 6/6] docs: MusicXML Compatibility --- docs/formats/musicxml.mdx | 1268 ++++++++++++++++- .../FileFormatFeatureTable/index.tsx | 35 +- 2 files changed, 1287 insertions(+), 16 deletions(-) diff --git a/docs/formats/musicxml.mdx b/docs/formats/musicxml.mdx index 2448901..ddc324c 100644 --- a/docs/formats/musicxml.mdx +++ b/docs/formats/musicxml.mdx @@ -3,6 +3,8 @@ title: MusicXML (.musicxml) description: The open file format format for exchanging music notation. --- +## Introduction + > The standard open format for exchanging digital sheet music. > > MusicXML was designed from the ground up for sharing sheet music files between applications, and for archiving sheet music files for use in the future. You can count on MusicXML files being readable and usable by a wide range of music notation applications, now and in the future. MusicXML complements the native file formats used by Finale and other programs, which are designed for rapid, interactive use. @@ -11,12 +13,1266 @@ description: The open file format format for exchanging music notation. **Compatibility Level:** Basic, good test coverage. -MusicXML is a very complex format and often also describes things rather visually than semantically. The format itself is very mature and supports a vast amount of -notation elements to be described. This also makes it quite complex to handle as applications might have to deal with elements which are not supported by the application itself. +MusicXML is a very complex format allowing the same thing to be specified in multiple different ways. The format itself is very mature and supports a vast amount of +notation elements to be described. This also makes it quite complex to handle as applications might have to deal with elements which are not supported by the application itself. -Additionally the different applications supporting MusicXML have their own slight dialects and expectations to where elements are placed. +Additionally the different applications supporting MusicXML have their own slight dialects and expectations to where elements are placed (as element positions can be relatively adjusted). This can easily cause visual discrepancies when exchanging files across applications. -| Feature | Reading and Data Model | Rendering | Audio Generation | alphaTex | -|---------|------------------------|-----------|------------------|----------| -| | | | | | \ No newline at end of file + +## Feature Table + +import { FileFormatFeatureTable, FileFormatFeatureGroup, FileFormatFeatureRow, FeatureStatus } from '@site/src/components/FileFormatFeatureTable' + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/components/FileFormatFeatureTable/index.tsx b/src/components/FileFormatFeatureTable/index.tsx index c00ba35..bb32f02 100644 --- a/src/components/FileFormatFeatureTable/index.tsx +++ b/src/components/FileFormatFeatureTable/index.tsx @@ -84,15 +84,25 @@ function computeFeatureStatistics(node: React.ReactNode): { ); let totalFeatures = featureRows.length; - let supportedFeatures = featureRows.filter((f) => { - const status = toFeatureStatusDefinitionFull(f.props.reading)?.status; - return ( - status === undefined || - status == FeatureStatus.Ignored || - status == FeatureStatus.Supported || - status == FeatureStatus.Unspecified - ); - }).length; + let supportedFeatures = featureRows + .map((f) => { + const status = toFeatureStatusDefinitionFull(f.props.reading)?.status; + if (status == undefined) { + return 1; + } + switch (status) { + case FeatureStatus.Supported: + case FeatureStatus.Ignored: + case FeatureStatus.Unspecified: + return 1; + case FeatureStatus.Partial: + return 0.5; + case FeatureStatus.NotSupported: + default: + return 0; + } + }) + .reduce((p, v) => p + v, 0); const relevantFeatures = featureRows.filter( (r) => @@ -136,7 +146,12 @@ export class FileFormatFeatureGroup extends React.Component<{ <>
    Feature
    - {this.props.title} + + {this.props.title} +