From 2fc742ebff9c21dd2fbde6a2bc1bfe712ac11300 Mon Sep 17 00:00:00 2001 From: Kim Wittenburg Date: Mon, 21 Jul 2025 21:44:48 +0200 Subject: [PATCH] Add Markdown Linting Linting allows us to ensure a more consistent formatting style of markdown files. --- .github/CONTRIBUTING.md | 16 ++++++ .github/PULL_REQUEST_TEMPLATE.md | 1 - .github/workflows/lint.yml | 19 +++++++ .markdownlint.yaml | 16 ++++++ README.md | 10 ++++ The UltraStar File Format (Unversioned).md | 55 ++++++++------------ The UltraStar File Format (v1).md | 58 +++++++++------------- The UltraStar File Format (v2).md | 53 ++++++++++---------- VERSIONING.md | 2 + 9 files changed, 133 insertions(+), 97 deletions(-) create mode 100644 .github/workflows/lint.yml create mode 100644 .markdownlint.yaml diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 5413ebf..53bde17 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,13 +1,29 @@ # Contributing Guide + We're open for Pull Requests. Our endgoal is to bond every community out there so we'd love to get in touch with you and partake in discussions on either [Issues](https://github.com/UltraStar-Deluxe/format/issues), [PR's](https://github.com/UltraStar-Deluxe/format/pulls) or [Discord - Format Related channel](https://discord.gg/tNEXZw2QJX) ## Setup your IDE + If you want to contribute please setup your IDE or Editor correctly. To do this you'll have to make sure the Editorconfig is used (works per default in VSCode) and that you have `pre-commit` installed so your commits are checked before pushing. ### Install & configure pre-commit (through python) + Please execute the following commands within the repositories root directory. This will install pre-commit to your system and installs the git hooks which check your changed code on commit if your changes adhere the conventions. + 1. `pip install pre-commit` 2. `pre-commit install` + +### Linting + +We want to ensure a consistent Markdown code style across this repository. +All markdown files will be linted via [`markdownlint-cli2-action`](https://github.com/DavidAnson/markdownlint-cli2-action). +You can run the linter locally by installing [`markdownlint-cli2`](https://github.com/DavidAnson/markdownlint-cli2) and then running + +```shell +markdownlint-cli2 "**/*.md" "#docs" "#.github/PULL_REQUEST_TEMPLATE.md" +``` + +We currently exclude the `docs` folder and the pull request template from the Markdown linting. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 0e20fd5..a337f8b 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -24,7 +24,6 @@ HOW TO WRITE A GOOD PULL REQUEST? - ### More - [ ] Added/updated documentation diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml new file mode 100644 index 0000000..ab86a7b --- /dev/null +++ b/.github/workflows/lint.yml @@ -0,0 +1,19 @@ +name: Linting +on: + push: + pull_request: + +jobs: + markdownlint: + name: Lint Markdown Files + runs-on: ubuntu-latest + steps: + - name: Check out Code + uses: actions/checkout@v4 + - name: Run markdownlint-cli2 + uses: DavidAnson/markdownlint-cli2-action@v20 + with: + globs: | + **/*.md + !.github/PULL_REQUEST_TEMPLATE.md + !docs diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000..22a30a0 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,16 @@ +default: true + +# We have long lines due to semantic line breaks. +MD013: false # line-length + +# GitHub understands subsequent blockquotes that are only separated by an empty line. +# This is required when using subsequent NOTE/TIP/WARNING blocks. +MD028: false # no-blanks-blockuote + +# We want to use GitHub's summary/details blocks. +MD033: # no-inline-html + allowed_elements: [summary, details] + +# The PULL_REQUEST_TEMPLATE.md does not meet this rule. +# We exclude linting on that file. +# MD041: false # first-line-h1 diff --git a/README.md b/README.md index 831211e..d67df84 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,9 @@ # UltraStar Format Specification + This specification contains a set of rules and requirements that dictate what an UltraStar textfile is and how each item should be interpreted. ## The problem + The idea for this specification came up within the [UltraStar* Creators Community Discord](https://discord.gg/tNEXZw2QJX) as we've been roaming free following some guidelines posted at many places on the internet for over a decade. Many programs (creator software, website hosts and karaoke software) try their best effort to support the respective tags and NoteTypes to support all the features we want. But it's been long enough and we need to standardize things to sustain the future of our precious format. @@ -9,16 +11,20 @@ Currently there are thousands of textfiles laying around unversioned and some wi There are several communities out there who do not talk to eachother so it's hard to come up with a definitive system. Let's bond together and see if we can make the best out of this format we all love. ## The endgoal + The endgoal for this project would be to: + * [ ] Bring the different communities on par with eachother to increase the quality of the produced textfiles * [ ] Versionise the format so we can improve and add features to it * [ ] Give each Tag or NoteType a definition and how it should be working ## Involved parties + Since the text format was introduced a little bit more than a decade ago alot of projects got to know and support it. We'd like to give these projects a little bit of appreciation by linking to their respective GitHub page or website. ### Karaoke software + * [UltraStar Online](http://ultrastaronline.com/) * [UltraStar Deluxe](https://github.com/UltraStar-Deluxe/USDX) * [Performous](https://github.com/performous/performous) @@ -28,6 +34,7 @@ We'd like to give these projects a little bit of appreciation by linking to thei * [UltraStar Play / Melody Mania](https://github.com/UltraStar-Deluxe/Play) ### UltraStar Song Creator software + * [Yass](https://github.com/SarutaSan72/Yass) * [Yass Reloaded](https://github.com/DoubleDee73/Yass) * [Composer](https://github.com/performous/composer) @@ -36,13 +43,16 @@ We'd like to give these projects a little bit of appreciation by linking to thei * [UltraSinger](https://github.com/rakuri255/UltraSinger) ### UltraStar Textfiles hosting + * [USDB](https://usdb.animux.de) * [UltraStar-ES](http://ultrastar-es.org/) ### Management Software + * [USDB Syncer](https://github.com/bohning/usdb_syncer) * [UltraStar Manager](https://github.com/UltraStar-Deluxe/UltraStar-Manager) ## Public Status Board + Do you wanna take part? Or monitor the progress? Then check out our [public status and release board](https://github.com/orgs/UltraStar-Deluxe/projects/3/views/1) and [milestones](https://github.com/UltraStar-Deluxe/format/milestones)! diff --git a/The UltraStar File Format (Unversioned).md b/The UltraStar File Format (Unversioned).md index 3b096bb..974f926 100644 --- a/The UltraStar File Format (Unversioned).md +++ b/The UltraStar File Format (Unversioned).md @@ -10,7 +10,6 @@ This document aims to provide a reference for existing songs as well as a baseli Note that version 1.0.0 of the file format is generally backward-compatible and can be used in almost all legacy applications. > [!IMPORTANT] -> > The unversioned UltraStar file format is archived. > According to the [versioning policy](https://github.com/UltraStar-Deluxe/format/blob/main/VERSIONING.md) no new features and changes will be introduced into this document. @@ -133,7 +132,6 @@ These file references are always relative to the song from which they are refere As a security measure implementations SHOULD NOT allow the use of absolute paths. > [!IMPORTANT] -> > In Windows file names are case-insensitive (i.e. there cannot be two files in a folder that differ only by their case). > Linux and macOS however, use fully case-sensitive file systems. > Implementations might need to pay special attention to this fact to ensure that files are compatible across all systems. @@ -147,7 +145,7 @@ The presence of this header is enough to indicate that a specific file format ve ### 3.3. The `#BPM` Header -``` +```text Required: Yes Syntax: 1*DIGIT [ (period / comma) 1*DIGIT ] ``` @@ -160,7 +158,7 @@ The value of this tag is arbitrary in the sense that it is usually 1 to 2 times ### 3.4. The `#MP3` Header -``` +```text Required: Yes ``` @@ -169,7 +167,7 @@ Supported audio formats are an implementation detail. ### 3.5. The `#TITLE` Header -``` +```text Required: Yes ``` @@ -177,7 +175,7 @@ The `TITLE` header indicates the title of the song. ### 3.6. The `#ARTIST` Header -``` +```text Required: Yes ``` @@ -185,7 +183,7 @@ The `ARTIST` header indicates the artist of the song. ### 3.7. The `#COVER`, `#BACKGROUND`, and `#VIDEO` Headers -``` +```text Required: No ``` @@ -195,7 +193,7 @@ Supported image and video formats are an implementation detail. ### 3.8. The `#GAP` Header -``` +```text Required: No Syntax: 1*DIGIT [ (period / comma) 1*DIGIT ] ``` @@ -205,7 +203,7 @@ This effectively offsets all notes in a song by this amount of time relative to ### 3.9. The `#VIDEOGAP` Header -``` +```text Required: No Syntax: [ minus ] 1*DIGIT [ (period / comma) 1*DIGIT ] ``` @@ -215,7 +213,7 @@ Negative values indicate that the indicated amount of time should be skipped at ### 3.10. The `#START` and `#END` Headers -``` +```text Required: No Syntax: 1*DIGIT [ (period / comma) 1*DIGIT ] ``` @@ -226,18 +224,16 @@ The `#START` and `#END` header specify two time points relative to the start of Game implementations SHOULD start and end the song at the specified points and scale scoring accordingly. > [!NOTE] -> > There are known implementations that only support integer values for `#END`. > In the interest of compatibility it is recommended to restrict values to integers. > [!NOTE] -> > The `#START` and `#END` values do not affect the placement of notes nor any other time codes relative to the audio. > They simply indicate that a song should be started or stopped a certain amount of time into the audio file. ### 3.11. The `#PREVIEWSTART` Header -``` +```text Required: No Syntax: 1*DIGIT [ (period / comma) 1*DIGIT ] ``` @@ -248,7 +244,7 @@ In its absence implementations SHOULD default to the start of the medley section ### 3.12. The `#MEDLEYSTARTBEAT` and `#MEDLEYENDBEAT` Headers -``` +```text Required: No Syntax: 1*DIGIT ``` @@ -258,7 +254,7 @@ Implementations MUST respect the `#GAP` value when calculating the medley start ### 3.13. The `#YEAR` Header -``` +```text Required: No Syntax: 4DIGIT ``` @@ -268,7 +264,7 @@ The value is a positive integer. ### 3.14. The `#GENRE` Header -``` +```text Required: No ``` @@ -277,31 +273,29 @@ For consistency, it is usually best to capitalize genres. ### 3.15. The `#LANGUAGE` Header -``` +```text Required: No ``` The `#LANGUAGE` header indicates the spoken or sung language(s) of a song. > [!NOTE] -> > Later versions of the file format impose restrictions on the set of valid values for this header. ### 3.16. The `#EDITION` Header -``` +```text Required: No ``` The `#EDITION` is an arbitrary categorization value. > [!NOTE] -> > Later versions of the file format impose restrictions on the set of valid values for this header. ### 3.17. The `#P1` and `#P2` Headers -``` +```text Required: No ``` @@ -310,12 +304,11 @@ These names correspond to the voices indicated by the `#P1` and `#P2` voice chan If the voices correspond to different singers in the original song, the header values often indicate the names of the original singers. > [!NOTE] -> > As `P0` is not a valid voice change, the header `P0` is not specified. ### 3.18. The `#DUETSINGERP1` and `#DUETSINGERP2` Headers -``` +```text Required: No ``` @@ -324,7 +317,7 @@ If both are specified [`#P1` and `#P2`](#317-the-p1-and-p2-headers) take precede ### 3.19. The `#CREATOR` Header -``` +```text Required: No ``` @@ -332,13 +325,12 @@ The `#CREATOR` indicates who created the UltraStar song. Values are usually usernames or gamer tags. > [!NOTE] -> > Some implementations are known to use an application-specific header `#AUTHOR` in place of `#CREATOR`. > The semantics of the `AUTHOR` header are not part of this specification. ### 3.20. The `#COMMENT` Header -``` +```text Required: No ``` @@ -347,7 +339,7 @@ Implementations MUST NOT assign semantics to the value of this header. ### 3.21. The `#ENCODING` Header -``` +```text Required: No Syntax: "UTF-8" / "CP1252" / "CP1250" ``` @@ -358,18 +350,16 @@ Implementations MAY support additional encodings. Names of encodings are compared in a case-insensitive manner. > [!IMPORTANT] -> > Many implementations only apply the specified encoding to **subsequent** headers and note texts. > Although this is technically not spec-compliant it is usually best to put the `ENCODING` header first. > [!WARNING] -> > Use of the `#ENCODING` tag is highly discouraged. > Songs must always use the UTF-8 encoding. ### 3.22. The `#RELATIVE` Header -``` +```text Required: No Syntax: "yes" / "no" ``` @@ -386,6 +376,7 @@ body = *( note / voice-change / empty-line ) ``` + The sequence of notes and end-of-phrase markers for each voice SHOULD appear in ascending order by their start beats. ### 4.1. Notes @@ -422,7 +413,6 @@ The pitch of a note is encoded as the number of half-steps relative to `C4` (als So a pitch of `5` represent an `F4` and a pitch of `-2` represents an `A#3`. > [!NOTE] -> > The pitches in this paragraph use [scientific pitch notation](https://en.wikipedia.org/wiki/Scientific_pitch_notation). #### 4.1.1. Regular Notes `:` @@ -493,11 +483,9 @@ To improve readability notes for different voices should not be interlaced. Each voice change SHOULD only appear once in ascending order of `voice-number`. > [!NOTE] -> > A voice change does NOT implicitly add an end-of-phrase indicator. > [!TIP] -> > A song that makes use of voice changes is referred to as a “duet”. ## Appendix @@ -532,7 +520,6 @@ In relative mode the semantics of start times changes for notes and end-of-phras After the start time of the end-of-phrase marker has been interpreted, the `rel-offset` value is added to `rel` for subsequent lines. > [!IMPORTANT] -> > In relative mode the order of notes and end-of-phrase markers within a file is significant. In files with multiple voices each voice has its own `rel` value which is independent of other voices. diff --git a/The UltraStar File Format (v1).md b/The UltraStar File Format (v1).md index 3b50a0c..05e61a0 100644 --- a/The UltraStar File Format (v1).md +++ b/The UltraStar File Format (v1).md @@ -9,7 +9,6 @@ Version 1.0.0 of the UltraStar file format has been officially published in 2023 Any future revisions to this document will only introduce backward-compatible changes. > [!NOTE] -> > For historical reasons version 1.1.0 is equivalent to version 1.0.0. [GitHub Issues](https://github.com/ultrastar-deluxe/format/issues) are preferred for discussion of this specification. @@ -155,7 +154,6 @@ As a security measure implementations SHOULD NOT allow the use of absolute paths > Linux and macOS however, use fully case-sensitive file systems. > Implementations might need to pay special attention to this fact to ensure that files are compatible across all systems. - ### 3.3. Core Headers This section describes the core headers of the file format. @@ -164,7 +162,7 @@ If no syntax is specified any valid `header-value` is valid. #### 3.3.1. The `#VERSION` Header -``` +```text Required: Yes Syntax: "1" period 1*DIGIT period 1*DIGIT ``` @@ -182,12 +180,11 @@ in particular if the value is syntactically invalid. The `#VERSION` header SHOULD be the first header in a file. > [!NOTE] -> > The absence of the `#VERSION` header indicates use of the unversioned UltraStar file format. #### 3.3.2. The `#BPM` Header -``` +```text Required: Yes Syntax: 1*DIGIT [ (period / comma) 1*DIGIT ] ``` @@ -200,7 +197,7 @@ The value of this tag is arbitrary in the sense that it is usually 1 to 2 times #### 3.3.3. The `#MP3` Header -``` +```text Required: Yes ``` @@ -210,7 +207,7 @@ Supported audio formats are an implementation detail. #### 3.3.4. The `#TITLE` Header -``` +```text Required: Yes ``` @@ -219,7 +216,7 @@ categorization is provided using dedicated headers like `RENDITION`, `EDITION`, #### 3.3.5. The `#ARTIST` Header -``` +```text Required: Yes ``` @@ -227,7 +224,7 @@ The `#ARTIST` header indicates the artist of the song. #### 3.3.6. The `#GAP` Header -``` +```text Required: No Syntax: 1*DIGIT [ (period / comma) 1*DIGIT ] ``` @@ -237,7 +234,7 @@ This effectively offsets all notes in a song by this amount of time relative to #### 3.3.7. The `#START` and `#END` Headers -``` +```text Required: No Syntax: 1*DIGIT [ (period / comma) 1*DIGIT ] ``` @@ -248,18 +245,16 @@ The `#START` and `#END` header specify two time points relative to the start of Game implementations SHOULD start and end the song at the specified points and scale scoring accordingly. > [!NOTE] -> > There are known implementations that only support integer values for `#END`. > In the interest of compatibility it is recommended to restrict values to integers. > [!NOTE] -> > The `#START` and `#END` values do not affect the placement of notes nor any other time codes relative to the audio. > They simply indicate that a song should be started or stopped a certain amount of time into the audio file. #### 3.3.8. The `#P1` thru `#P9` Headers -``` +```text Required: Yes for multi-voice songs, No for single-voice songs ``` @@ -272,7 +267,6 @@ i.e. the header `#P2` indicates the name of the voice whose notes are introduced If a song uses the voice change `Pn` the corresponding `#Pn` header is required. > [!NOTE] -> > As `P0` is not a valid voice change, the header `#P0` is not specified. ## 4. The File Body @@ -285,6 +279,7 @@ body = *( note / voice-change / empty-line ) ``` + The sequence of notes and end-of-phrase markers for each voice SHOULD appear in ascending order by their start beats. ### 4.1. Notes @@ -323,7 +318,6 @@ The pitch of a note is encoded as the number of half-steps relative to `C4` (als So a pitch of `5` represent an `F4` and a pitch of `-2` represents an `A#3`. > [!NOTE] -> > The pitches in this paragraph use [scientific pitch notation](https://en.wikipedia.org/wiki/Scientific_pitch_notation). The text of a note contains the spoken words of that note (usually a single syllable). There are no restrictions on the specific text values, in particular spaces can appear at the beginning or end of the note text (or both). @@ -344,7 +338,6 @@ and after are semantically equivalent. (the `|` is used to mark the end of the line for visualization purposes in the above example) - #### 4.1.1. Regular Notes `:` A regular note is indicated by the note type `:` (colon, `%x3A`). @@ -413,7 +406,6 @@ If the body of a song does not start with a voice change, `P1` is assumed implic To improve readability notes for different voices should not be interlaced. > [!NOTE] -> > A voice change does NOT implicitly add an end-of-phrase indicator. Voice changes SHOULD appear in ascending order of `voice-number` and there SHOULD be no gaps (i.e. a song having notes for `P1` and `P3`, but not `P2`). @@ -421,7 +413,6 @@ The exact `voice-number` carries no semantics other than its relative order with In particular a file that uses `P3` and `P5` can be rewritten using `P1` and `P2` with no change in semantics. > [!TIP] -> > A song that makes use of voice changes is referred to as a “duet”. A song that uses voice changes MUST also include the appropriate [`#P1` thru `#P9`](#338-the-p1-thru-p9-headers) headers indicating the names of the voices. @@ -455,7 +446,7 @@ to give users the option of changing the volume of vocal and instrumental tracks #### A.4. The `#VIDEOGAP` Header -``` +```text Syntax: [ minus ] 1*DIGIT [ (period / comma) 1*DIGIT ] ``` @@ -464,7 +455,7 @@ Negative values indicate that the indicated amount of time should be skipped at #### A.5. The `#PREVIEWSTART` Header -``` +```text Syntax: 1*DIGIT [ (period / comma) 1*DIGIT ] ``` @@ -474,7 +465,7 @@ In its absence implementations SHOULD default to the start of the medley section #### A.6. The `#MEDLEYSTARTBEAT` and `#MEDLEYENDBEAT` Headers -``` +```text Syntax: 1*DIGIT ``` @@ -483,7 +474,7 @@ Implementations MUST respect the `GAP` value when calculating the medley start a #### A.7. The `#YEAR` Header -``` +```text Syntax: 4DIGIT ``` @@ -543,9 +534,9 @@ The curated list contains: - Video Game - Viral Hit -A list of eligable SingStar editions is available [here](https://github.com/bohning/usdb_syncer/wiki/SingStar-Editions). -A list of eligable RockBand editions is available [here](https://github.com/bohning/usdb_syncer/wiki/RockBand-Editions). -A list of eligable Guitar Hero editions is available [here](https://github.com/bohning/usdb_syncer/wiki/GuitarHero-Editions). +A list of eligable SingStar editions is available [on GitHub](https://github.com/bohning/usdb_syncer/wiki/SingStar-Editions). +A list of eligable RockBand editions is available [on GitHub](https://github.com/bohning/usdb_syncer/wiki/RockBand-Editions). +A list of eligable Guitar Hero editions is available [on GitHub](https://github.com/bohning/usdb_syncer/wiki/GuitarHero-Editions). For arbitrary keywords see the [`#TAGS`](#a11-the-tags-header) header. #### A.11. The `#TAGS` Header @@ -561,7 +552,6 @@ Multiple values can be separated by a comma (`%x2C`). Values are usually usernames or gamer tags. > [!NOTE] -> > Some implementations are known to use an application-specific header `#AUTHOR` in place of `#CREATOR`. > The semantics of the `#AUTHOR` header are not part of this specification. @@ -578,7 +568,7 @@ Implementations MUST NOT assign semantics to the value of this header. #### A.15. The `#AUDIOURL`, `#VIDEOURL`, `#COVERURL` and `#BACKGROUNDURL` Header -``` +```text Syntax: URL ``` @@ -593,13 +583,13 @@ the same artist—or even different edits of the same performance—are common. Examples: -- video version -- album version -- live -- live (Malmö 2024) -- radio edit -- extended version -- uncensored +- video version +- album version +- live +- live (Malmö 2024) +- radio edit +- extended version +- uncensored ## Revision History diff --git a/The UltraStar File Format (v2).md b/The UltraStar File Format (v2).md index c983533..d7fa810 100644 --- a/The UltraStar File Format (v2).md +++ b/The UltraStar File Format (v2).md @@ -142,7 +142,6 @@ If an application-specific header at some point becomes standardized, the standa Implementations MUST ignore headers they do not recognize. The order of headers is irrelevant although standardized headers should precede any application-specific headers. - ### 3.2. File References Some headers reference other files, most notably `#AUDIO`, `#VIDEO`, `#COVER`, and `#BACKGROUND`. @@ -164,7 +163,7 @@ If no syntax is specified any valid `header-value` is valid. #### 3.3.1. The `#VERSION` Header -``` +```text Required: Yes Syntax: 1*DIGIT period 1*DIGIT period 1*DIGIT ``` @@ -187,7 +186,7 @@ The `#VERSION` header SHOULD be the first header in a file. #### 3.3.2. The `#BPM` Header -``` +```text Required: Yes Syntax: 1*DIGIT [ period 1*DIGIT ] ``` @@ -199,7 +198,7 @@ The value of this tag is arbitrary in the sense that it is usually 4 to 8 times #### 3.3.3. The `#AUDIO` Header -``` +```text Required: Yes ``` @@ -209,7 +208,7 @@ Supported audio formats are an implementation detail. #### 3.3.4. The `#TITLE` Header -``` +```text Required: Yes ``` @@ -218,7 +217,7 @@ categorization is provided using dedicated headers like `RENDITION`, `EDITION`, #### 3.3.5. The `#ARTIST` Header -``` +```text Required: Yes ``` @@ -226,7 +225,7 @@ The `#ARTIST` header indicates the artist of the song. #### 3.3.6. The `#GAP` Header -``` +```text Required: No Syntax: 1*DIGIT ``` @@ -237,7 +236,7 @@ The `GAP` value is an integer. #### 3.3.7. The `#START` and `#END` Headers -``` +```text Required: No Syntax: 1*DIGIT ``` @@ -247,13 +246,12 @@ Game implementations SHOULD start and end the song at the specified points and s Both `#START` and `#END` values are integers. > [!NOTE] -> > The `#START` and `#END` values do not affect the placement of notes nor any other time codes relative to the audio. > They simply indicate that a song should be started or stopped a certain amount of time into the audio file. #### 3.3.8. The `#P1` thru `#P9` Headers -``` +```text Required: Yes for multi-voice songs, No for single-voice songs ``` @@ -266,7 +264,6 @@ i.e. the header `#P2` indicates the name of the voice whose notes are introduced If a song uses the voice change `Pn` the corresponding `#Pn` header is required. > [!NOTE] -> > As `P0` is not a valid voice change, the header `#P0` is not specified. ## 4. The File Body @@ -279,6 +276,7 @@ body = *( note / voice-change / empty-line ) ``` + The sequence of notes and end-of-phrase markers for each voice MUST appear in ascending order by their start beats. ### 4.1. Notes @@ -338,7 +336,6 @@ and after are semantically equivalent. (the `|` is used to mark the end of the line for visualization purposes in the above example) - #### 4.1.1. Regular Notes `:` A regular note is indicated by the note type `:` (colon, `%x3A`). @@ -440,12 +437,12 @@ Supported image and video formats are an implementation detail. The `#VOCALS` and `#INSTRUMENTAL` header contain file references to audio files (as defined in [Section 3.2](#32-file-references)). These files contain the a cappella and instrumental versions of the song respectively. -Implementations MAY use these instead of [`#MP3`](#333-the-mp3-header) +Implementations MAY use these instead of [`#AUDIO`](#333-the-audio-header) to give users the option of changing the volume of vocal and instrumental tracks separately. #### A.3. The `#VIDEOGAP` Header -``` +```text Syntax: [ minus ] 1*DIGIT ``` @@ -454,7 +451,7 @@ Negative values indicate that the indicated amount of time should be skipped at #### A.4. The `#PREVIEWSTART` Header -``` +```text Syntax: 1*DIGIT ``` @@ -464,7 +461,7 @@ In its absence implementations SHOULD default to the start of the medley section #### A.5. The `#MEDLEYSTART` and `#MEDLEYEND` Headers -``` +```text Syntax: 1*DIGIT ``` @@ -472,7 +469,7 @@ The `#MEDLEYSTART` and `#MEDLEYEND` headers indicate in milliseconds the start a #### A.6. The `#YEAR` Header -``` +```text Syntax: 4DIGIT ``` @@ -532,9 +529,9 @@ The curated list contains: - Video Game - Viral Hit -A list of eligable SingStar editions is available [here](https://github.com/bohning/usdb_syncer/wiki/SingStar-Editions). -A list of eligable RockBand editions is available [here](https://github.com/bohning/usdb_syncer/wiki/RockBand-Editions). -A list of eligable Guitar Hero editions is available [here](https://github.com/bohning/usdb_syncer/wiki/GuitarHero-Editions). +A list of eligable SingStar editions is available [on GitHub](https://github.com/bohning/usdb_syncer/wiki/SingStar-Editions). +A list of eligable RockBand editions is available [on GitHub](https://github.com/bohning/usdb_syncer/wiki/RockBand-Editions). +A list of eligable Guitar Hero editions is available [on GitHub](https://github.com/bohning/usdb_syncer/wiki/GuitarHero-Editions). For arbitrary keywords see the [`TAGS`](#a10-the-tags-header) header. #### A.10. The `#TAGS` Header @@ -562,7 +559,7 @@ Implementations MUST NOT assign semantics to the value of this header. #### A.14. The `#AUDIOURL`, `#VIDEOURL`, `#COVERURL` and `#BACKGROUNDURL` Header -``` +```text Syntax: URL ``` @@ -577,13 +574,13 @@ the same artist—or even different edits of the same performance—are common. Examples: -- video version -- album version -- live -- live (Malmö 2024) -- radio edit -- extended version -- uncensored +- video version +- album version +- live +- live (Malmö 2024) +- radio edit +- extended version +- uncensored ## Revision History diff --git a/VERSIONING.md b/VERSIONING.md index eb62d4f..b4e4347 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -68,10 +68,12 @@ In face of changes to the format and new features being added this header basica Implementations may safely load any song that uses a major version of the file format known to the implementation. The following guarantees are upheld by the specification team: + - Revisions to a published version of the UltraStar file format will only make backwards-compatible changes. - Minor versions of the UltraStar file format will only introduce backward-compatible changes compared to the respective major version. Backward-compatible changes include (but are not limited to): + - Editorial changes - Standardization of metadata headers - Increasing the strictness on syntax requirements