Release UltraStar Song Format v1.2.0

[marwin89]

Task

Release Official UltraStar Song Format v1.2.0 according to Roadmap

Introduce #22 URL-Header (AUDIOURL, COVERURL, BACKGROUNDURL and VIDEOURL) in

• "spec.md" - Specification Document
• "usdx.eu/format"-Website

[codello]

Can we clarify the intent behind versioning the file format? Versioning for a file format works differently to versioning an application. It is easy to update an application to get new features but it can be hard to update a file format to a new version. IMO a new version of the format should be carefully considered.

I would personally expect that a file format change marks an expected change in behavior (that might be backwards-compatible). I don't think the current change set (basically #22) qualifies for that. We can just add these headers to version 1.2.0 without breaking anything. The headers are optional anyways.

In other words: Take an example application that implements the AUDIOURL header. Now take the following song file:

#VERSION: 1.1.0
#AUDIOURL: https://youtube.com/...
…

The AUDIOURL header is not defined in version 1.1.0. Should it be ignored? I personally think it is more clear to amend versions with backwards-compatible changes as long as possible and try to introduce as few versions as possible to avoid an overly complicated compatibility matrix of features/headers and versions.

[Baklap4]

Currently versioning in semver has been agreed upon as per #13
We achieve transparancy in what is being changed in which version. Each change is carefully considered so we dont break compatibility.. as of yet we didnt have to update the major version.

This also allows us to deprecate things we want to phase out.

In the end a karaoke program can opt in to support a specific version. Each txt annotated with that should be compatible. Currently the usdb syncer supports up to 1.2.0.
Same for Ultrasinger. Ideally we would add this to hosting parties (usdb) itself too.. so people can download the correct version for the software theyre using, but that means bigger changes there.

As for headers not specified in the format, they should not break the game experience. Therefore we would suggest to ignore them, rendering them useless. If a new header is needed the format team will have a discussion about it to unify its existence

[codello]

Ok, I understand. While I disagree with some of the decisions in #13 I can accept that the decision is final.

My concern is mostly that a larger number of versions can lead to confusion which header is available in which version. Even if the specification is clear about this, I see a risk that an implementation respects all headers it supports, regardless of the version specified by the file. For example I could imagine that an implementation would respect the AUDIOURL in a song with version 1.1.0. This is not inherently problematic but if enough implementations do this then the version number becomes meaningless. I'm especially worried that at some point song creators will use wrong version numbers "because it works anyways" (I don't expect song creators to be familiar with the formal specification).

But maybe I'm overcomplicating things here and all that is not really a problem…

[Baklap4]

Tooling for creating songs should aim to support the latest version available. Therefore newer txt files will eventually be only made and distributed within the latest format. I don't expect song creators to know about the specification, however the tooling they're using should guide them into using the latest format i'd suppose.

Within usdb_syncer there's now an option to select a specific version cause not every karaoke software has implemented every version yet. This way you can set it once depending on the software you're using.

Personally i think if a version is specified, the program should aim to just support whatever is specified in said version. The software can however support more than what's specified. This is a nicety, but shouldn't be mandatory. This leads to software implementing at least a specific version where a standard has been defined. A new karaoke software can then more easily be released since it can opt to just support 0.3.0 at the first version, but support more in the end. This makes for faster development cycles.

I see a risk that an implementation respects all headers it supports, regardless of the version specified by the file. For example I could imagine that an implementation would respect the AUDIOURL in a song with version 1.1.0.

This is like you said not inherently a problem, the #VERSION header is mainly there to guide the developers on what to support in their software. Song creator tooling should aim to only release txt files with latest version (for now a selection since karaoke software is currently lacking support) -> https://www.open-music-games.org/play-and-create/games
As the format project i'd love to see a table within the readme specifying which project currently supports which version. And as mentioned in #32 release badges for programs to state that they do support said version

In the end i think it's good we defined versions, this way it's clear what each version contains and supports -> see the spreadsheet -> https://docs.google.com/spreadsheets/d/13fj_wtRHbSjaOaS1ehmCogoeFV9MyqY1eeiqkrJfhDA/edit?usp=sharing -> This might need to be better documented within the website/spec

This will also allow the developers to come up with new headers/functionality if they need to be there (as a result see 1.0.0, 1.1.0 and 1.2.0). Which are defined in unity rather than on a per project basis.
The end-user (singers) will get the best experience when they'll get the latest version of txt files out there. Albeit that the singing software is not up-to-date for versioning yet

[Baklap4]

Specfile has been merged already; website still needs an update, @marwin89 can you fix this?

[codello]

Thank you for the explanation @Baklap4. I can understand that perspective. I still think I am in disagreement though.

Personally i think if a version is specified, the program should aim to just support whatever is specified in said version. The software can however support more than what's specified. […] This leads to software implementing at least a specific version where a standard has been defined.

To me it feels like we are using the version to indicate a specific set of features of the format. #32 kind of reinforces this impression. However, I think that the main purpose of a versioned file format is to ensure compatibility. To me a new version of a file format indicates a change in compatibility (potentially non-breaking but a change nontheless). I wouldn't necessarily consider the introduction of new metadata a change in compatibility (compared to - for example - the introduction of a new note type).

In the end i think it's good we defined versions, this way it's clear what each version contains and supports

Definitely agree. I'm all for versioning. I do think, however, that it would benefit compatibility and adoption if we keep the number of different versions low and not try to release new versions quickly or regularly. This doesn't mean that new headers shouldn't be standardized, I just don't see the benefit increasing the version number for that.

As the format project i'd love to see a table within the readme specifying which project currently supports which version.

+1

[marwin89]

Specfile has been merged already; website still needs an update, @marwin89 can you fix this?

Hi @Baklap4 , I'll try to do it in 1-2 weeks 👍🏻 I got a lot to do in my job.