search

UltraStar-Deluxe / format

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

[Spec] Unify and simplify time data #24

Closed achimmihca closed 10 months ago

achimmihca commented 1 year ago

Suggestion

The units in the UltraStar txt format are bonkers.

Some fields use seconds, some milliseconds, some beats. The units in some cases are not even symmetric.

For example,

To make things easier, I suggest to

My suggested units are

The following would then be equivalent

#START:500ms
#END:1000ms
#START:500  ms
#END:1.0 s
#START:0.5
#END:1000

Use case

As I user, I do not need to look up the unit of a field again and again.

Extra info/examples/attachments

No response

bohning commented 1 year ago

Yes, it would be great to get rid of these inconsistencies (dating back to the original Corvus’ UltraStar)...

Baklap4 commented 1 year ago

This wouldn't break compatibility up untill we remove support for the last example. Clever thinking and yes i'd really love this improvement of the format!

As an addition i wouldn't support decimals if you need that fine granualarity please use the correct unit: ms. This can also be done by hosting websites which normalizes the values into ms so we are consistent with the units instead of mixing them.

Also what would be the unit for beats?

achimmihca commented 1 year ago

i wouldn't support decimals

Good point. Then maybe we should only allow milliseconds but not seconds?

Also what would be the unit for beats?

Why not b or beats?

Note that there are currently fields like #PREVIEWSTARTBEAT. Maybe this should become #PREVIEWSTART such that other units are also allowed.

marwin89 commented 12 months ago

Is something like this possible? m:s:ms

#START: 01:03:800
Baklap4 commented 12 months ago

Is something like this possible? m:s:ms

#START: 01:03:800

Hmm that'd need a lot of parsing and can get inconsistent across locales.

I think TimeUnits are great, but even better maybe would be to only use one unit? I'd suppose ms fits best in there.. except we already have 2 units: Time and 'Beats' If we're going to fully time based this would need a major version bump unless a fallback of beats can be used.

We might wanna think a bit more about this one

marwin89 commented 12 months ago

Hmm that'd need a lot of parsing and can get inconsistent across locales.

thanks, I understand.

I think both solutions are appealing. Its a progress anyway 👍 I support both.

  1. using time units (easy to read and intuitive) (@achimmihca )
  2. just use milliseconds (keep it simple) (@Baklap4)

Here is my suggestion building upon 1:

  1. using time units m=minute, s=seconds, ms=milliseconds, no float values, beats=beats
#START: 1m 11s 100ms
#END: 3m 27s 250ms
#MEDLEYSTARTBEAT: 30beats
marwin89 commented 12 months ago

SUMMARY

So here is the summary for this issue up till now. (incl. discussion below)

#GAP: 4500
#VIDEOGAP: 1200
#START: 21100
#END: 223250
#MEDLEY: 110-208
#PREVIEWSTART: 45200

The description in the spec (website) will be updated to:

GAP Delay for the start the lyric in milliseconds. Its used that the first word starts at 0. Otherwise the delay gap would be added to the start of the first line.... VIDEOGAP Specifies the delay in milliseconds between the start of the video and the start of the song. This value can be used to synchronize the video with the music.... START START specifies the time in milliseconds from the beginning of the audio file at which the song starts. This value can be used to skip any silence or intro at the beginning of the audio file. The value should be positive integers that represent the start time of the song in seconds.. END Specifies the time in milliseconds from the beginning of the audio file at which the song ends. .... PREVIEWSTART Specifies the time in milliseconds from the beginning of the audio file at which the preview of the song starts.....

Baklap4 commented 12 months ago

⚠️With this unifying of the units we'll introduce a breaking change instead of smoothly moving over and deprecating whereas the first approach mentioned (just add the unit) doesn't break as it can invoke a fall-back mechnism ⚠️

bohning commented 12 months ago

I know I am late to the game, but I would have been happy with just harmonizing everything (except beat-based) to milliseconds, and then go without unit. Keep it simple and consistent. For medley, I used medley=start-stopin the Syncer (as USDB currently deletes the medley tags) - I think it makes more sense to define the medley section in one tag, e.g. #MEDLEY:start-stop (and beats is implicit). One without the other makes no sense (I mean #MEDLEYSTARTBEAT and #MEDLEYENDBEAT), so it makes more sense to define the medley section in a single tag IMHO.

achimmihca commented 12 months ago

I strongly suggest to use time units because we'll introduce a breaking change instead of smoothly moving over and deprecating. Introducing such a breaking change would cause issues, promised.

just harmonizing everything

(except beat-based) Hence, it not harmonized. As a txt editor, I still have to look up which unit is used instead of specifying what I want.

I think it makes more sense to define the medley section in one tag

I want to quote from #22: "why we are suddenly making the tags way more complex to parse and edit instead of keeping a flat, easy-to-understand structure".

start-stop would be a shorthand that is not needed, introducing new parsing.

One without the other makes no sense

You still need to handle start- or -end. Furthermore, -end could be confused with negative numbers (start - -end depending on GAP value).

The goal of my original proposal was to eliminate inconsistencies in the file format (different time units) and make it obvious how to read the value as a human.

Thus, my vote goes to an explicit ms time unit because

Optionally we can allow the beat time unit. But I think this is not even needed.

Further, my vote goes to separate #MEDLEYSTART and #MEDLEYEND (with time unit) because

marwin89 commented 12 months ago

2nd SUMMARY / VOTE NOW 📈 ✋

So here is the second summary for this issue. We are close to a final result.

Please vote for this issue till 15th nov 2023 with emoticon 🎉 / 🚀/ ❤️ .

We unify the time units in version 1.1.0. This means:

GAP, #VIDEOGAP, #START, #END, PREVIEWSTART, MEDLEYSTART, MEDLEYEND...

🚀 A: use only milliseconds with "ms"-unit. 🎉 B: use only milliseconds without"ms". ❤️ C: use milliseconds without"ms" + keep beats in MEDLEYSTART and MEDLEYEND.

other time units like seconds in these tags aren't allowed anymore.

🚀 A

#GAP: 4500ms
#VIDEOGAP: 1200ms
#START: 21100ms
#END: 223250ms
#MEDLEYSTART: 67050ms
#MEDLEYEND: 960020ms
#PREVIEWSTART: 45200ms

🎉 B

#GAP: 4500
#VIDEOGAP: 1200
#START: 21100
#END: 223250
#MEDLEYSTART: 67050
#MEDLEYEND: 960020
#PREVIEWSTART: 45200

❤️ C

#GAP: 4500
#VIDEOGAP: 1200
#START: 21100
#END: 223250
#MEDLEYSTART: 110
#MEDLEYEND: 208
#PREVIEWSTART: 45200

The description in the spec (website) will be updated to:

GAP Delay for the start the lyric in milliseconds. Its used that the first word starts at 0. Otherwise the delay gap would be added to the start of the first line.... VIDEOGAP Specifies the delay in milliseconds between the start of the video and the start of the song. This value can be used to synchronize the video with the music.... START START specifies the time in milliseconds from the beginning of the audio file at which the song starts. This value can be used to skip any silence or intro at the beginning of the audio file. The value should be positive integers that represent the start time of the song in seconds.. END Specifies the time in milliseconds from the beginning of the audio file at which the song ends. .... PREVIEWSTART Specifies the time in milliseconds from the beginning of the audio file at which the preview of the song starts.....

Baklap4 commented 11 months ago

These 3 options would mean a breaking change if we want this. It'd be nice to deprecate this in 0.3.0 and unify (break) it in 1.0.0. Or to deprecate it in 1.1.0 and break it in 2.0.0

Going for option B since a suffix of ms may mean that i can use other time units aswell (which isn't the case)

achimmihca commented 11 months ago

To avoid a breaking change, one could introduce new header fields, e.g., with a ...MS suffix:

#GAPMS: 4500
#VIDEOGAPMS: 1200
#STARTMS: 21100
#ENDMS: 223250
#MEDLEYSTARTMS: 67050
#MEDLEYENDMS: 960020
#PREVIEWSTARTMS: 45200

I think a non-breaking change is much better to achieve acceptance and adoption of the new format.

vote for this issue till next saturday

As pointed out by others, people (including devs) only interact occasionally with the UltraStar community, so there needs to be more time for voting.

marwin89 commented 11 months ago

These 3 options would mean a breaking change if we want this. It'd be nice to deprecate this in 0.3.0 and unify (break) it in 1.0.0. Or to deprecate it in 1.1.0 and break it in 2.0.0

@Baklap4 Let's deprecate it in 1.1.0 and break it in 2.0.0. Updated the semver approach (for devs) accordingly: Spreadsheat Version strategy Break in v2.0.0 would be in 2025-December. That's a long time to communicate (and even make a little update tool / script.)

I think a non-breaking change is much better to achieve acceptance and adoption of the new format.

@achimmihca you're right. however if we introduce new shiny features in 1.1.0 (2023) and ~1.2.0 (2024) and give players & game devs time till 2025 for v2.0.0 to adopt (good communication) we achieve an overall acceptance too. #Mp3 will also be removed in v2.0.0

Let's be couragous 🚀 some things will break on someones pc! I know we have to look for acceptance and breaking changes are dangerous! but with syncer and good content management in usdb its easier than ever for (even lazy) players to get complete song folders (on uptodate standards). or even a complete collection with better sound/video and image quality 🎉

achimmihca commented 11 months ago

With this unifying of the units we'll introduce a breaking change

With a #VERSION tag as suggested in #13, one could still support old behaviour. Further, one could tell users that things changed and they need to update their song files.

For this to work, the #VERSION tag must be mandatory (assuming legacy behaviour when missing).

marwin89 commented 10 months ago

SUMMARY / RESULT 🚩

Thanks for voting. Here is the final result for this issue.

We unify the time units all to milliseconds in version 2.0.0. without "ms" (option B). 5 🎉 / 2 🚀 / ❤ 0

This means:

#GAP: 4500
#VIDEOGAP: 1200
#START: 21100
#END: 223250
#MEDLEYSTART: 67050
#MEDLEYEND: 960020
#PREVIEWSTART: 45200

The description in the spec (website) will be updated to:

GAP Delay for the start the lyric in milliseconds. Its used that the first word starts at 0. Otherwise the delay gap would be added to the start of the first line.... VIDEOGAP Specifies the delay in milliseconds between the start of the video and the start of the song. This value can be used to synchronize the video with the music.... START START specifies the time in milliseconds from the beginning of the audio file at which the song starts. This value can be used to skip any silence or intro at the beginning of the audio file. The value should be positive integers that represent the start time of the song in seconds.. END Specifies the time in milliseconds from the beginning of the audio file at which the song ends. .... PREVIEWSTART Specifies the time in milliseconds from the beginning of the audio file at which the preview of the song starts.....