search

UltraStar-Deluxe / format

UltraStar Format Specification
https://usdx.eu/format
MIT License
12 stars 2 forks source link

[Spec] Core Headers and Extended Headers #57

Open codello opened 6 months ago

codello commented 6 months ago

Suggestion

I suggest that the spec divides standardized headers into two categories: Core headers and extended headers.

Core headers MUST be supported by compliant implementations. The idea is that a song that only makes use of core headers can be used in any compliant Karaoke game.

Extended headers have standardized syntax and semantics and may or may not be supported by implementations. As an example these could be the various metadata headers like #EDITION that are not relevant to the core Karaoke experience.

Use case

There are already a lot of standardized headers (over 30 at the time of writing). Currently there is no clear indication which headers are a core part of the format and which headers correspond to additional features that can enhance the game but are not actually required from a technical standpoint. This amount of headers makes it difficult for developers to build compliant applications as the more important parts can be drowned out by the amount of optional headers.

Extra info/examples/attachments

In practice I would expect core headers to remain in the spec just as they are now (i.e. in section 3). Extended headers could be moved into an appendix. This would also make the spec a lot more concise.

This suggestion originally came up in https://github.com/UltraStar-Deluxe/format/pull/48#discussion_r1477045268

State of the Suggestion

This section includes the list of core and extended headers as per this suggestion. I will update this list according to the discussion.

Core Headers

Extended Headers

marwin89 commented 6 months ago

Thanks for the work kim :) Let's discuss this.

  1. I would recommend to include Cover, Background and Video as core headers. Cause any popular Singing Game relies on visual representation. for me it feels strange to exclude them from core.
  2. And yes I agree, we could make an appendix for Extended Headers.
  3. Yes, we should definitely make a seperation between core and extended
codello commented 6 months ago

I thought about this as well. The reason I excluded them from the core headers is because I can imagine a very basic Karaoke implementation that doesn't use these headers. But maybe this is getting too complicated and we should do the categories based on our intention what the core Karaoke experience should be.

I have moved #COVER, #BACKGROUND, and #VIDEO into the core headers.

I also moved #P1 and #P2 to the extended headers. I would consider duets a core component of the format. However these headers only indicate the player names which I would consider an extended feature.

Baklap4 commented 6 months ago

I think we already did define the headers which are required to make games work from this definition came that #COVER #BACKGROUND and #VIDEO are not required, besides not every audio track has a video or even a cover or background

The bare minimum so sing karaoke is: Version, Title, Artist, MP3/Audio, BPM. Those are annotated with a * in the spec spreadsheet and live under their own "Mandatory attributes" header on the site.

Personally i'd keep the seperation required/not-required, whereas the not-required list is nice to opt in to and will help with a better experience by the enduser

codello commented 6 months ago

Ah good point with the mandatory / optional headers. I agree that the separation makes sense and we should keep that.

For me the difference between core and extended headers is a little bit different. All required headers are definitely core headers. But for example #GAP is not a required header (i.e. not every txt has to contain it), but I would consider it to be a core header (i.e. every implementation has to support it if it is present). On the other hand metadata fields such as #EDITION are optional and in addition implementations can safely ignore the header without breaking compatibility.

So basically required/optional defines whether a header must be present in a TXT file. Core/Extended defines whether an implementation has to support a specific header (if present). Extended headers can safely be ignored without breaking the song. At least that would be my idea.