Only fade background music when changing streams

[wjt]

Previously, the background music always faded out during the scene-exit
transition, then faded in during the scene-enter transition. This had:
two negative consequences:

1. It sounds bad when the successive scenes have the same music (e.g.
   the three waves of ink combat);
2. It means the opening chord of each new piece of music is guaranteed
   to be inaudible since the 1-second fade-in is still ongoing.

Instead:

• Do not fade the music when the scene fades out;
• When the new scene arrives, with a BackgroundMusic node:
  • If the stream is the same, do nothing (fixing point 1 above);
  • Else, fade out the old stream for 1 second, then start playing the
    new stream at full volume (fixing point 2 above).

To do this, move most of the logic from BackgroundMusic to MusicPlayer.
Remove the ability to pause/resume BackgroundMusic in the editor for
simplicity, leaving only Play/Stop.

Improve documentation of the two cooperating scripts.

Resolves #637

[github-actions]

Play this branch at https://play.threadbare.game/branches/endlessm/wjt/only-fade-background-music-when-changing-streams.

(This launches the game from the start, not directly at the change(s) in this pull request.)

[wjt]

Try playing from the second round of ink combat through to Fray's End:

https://play.threadbare.game/branches/endlessm/wjt/only-fade-background-music-when-changing-streams/#res://scenes/quests/lore_quests/quest_001/2_ink_combat/ink_combat_round_2.tscn

And compare it to the status quo:

https://play.threadbare.game/branches/endlessm/main/#res://scenes/quests/lore_quests/quest_001/2_ink_combat/ink_combat_round_2.tscn

1. Round 2 to round 3: previously would fade out and in the same track, now does not
2. Round 3: (unrelated to this PR) fades out the combat music and fades in the peaceful bed track
3. Round 3 to stealth: Fades out the peaceful bed, starts the stealth music from beat 1 (one of the things I was trying to fix)
4. Try getting caught in stealth: I think it sounds better not to fade the same track out and in
5. Stealth to cutscene: fades out stealth music for 1 second, starts peaceful bed from beat 1
6. Cutscene to Fray's End: no fade

Having implemented this, I'm not entirely sure it's an improvement, so I'm interested in other opinions.

• On the web there is sometimes a stutter when the scene changes. This is noticeable at "1" above.
• The last step, going back to Fray's End without a music fade, feels weird to me.
• 3, 4, 5 all sound better

[manuq]

I played it and overall I think it's an improvement. I love that the music keeps playing while the same level restarts, or when the next level has the same music and is related to the previous one (ink drinker rounds).

Having implemented this, I'm not entirely sure it's an improvement, so I'm interested in other opinions.

• On the web there is sometimes a stutter when the scene changes. This is noticeable at "1" above.

Yes, I could hear the stutter in my playtest. It was small but noticeable. Still I prefer the stutter than fading out/in the music in 1.

• The last step, going back to Fray's End without a music fade, feels weird to me.

Yes exactly. Maybe this can be a parameter of the Cinematic node? I think we are detecting 2 kinds of ellipsis:

• A short ellipsis: StoryWeaver travels a short distance or restart the same level (music doesn't fade).
• A long ellipsis. StoryWeaver travels a long distance (music fades).

Besides music we could also make them different by changing the duration. A short ellipse could happen faster and a long one can last more time. Currently all last 1 second (the transition default value).

• 3, 4, 5 all sound better

Agreed.

[wjt]

I played it and overall I think it's an improvement.

I think I will readd the play/stop controls in the editor before marking this as not a draft.

• On the web there is sometimes a stutter when the scene changes. This is noticeable at "1" above.

Yes, I could hear the stutter in my playtest. It was small but noticeable. Still I prefer the stutter than fading out/in the music in 1.

OK, I'll file a bug about this problem if this PR lands. I wonder what causes the stutter…

• The last step, going back to Fray's End without a music fade, feels weird to me.

Yes exactly. Maybe this can be a parameter of the Cinematic node? I think we are detecting 2 kinds of ellipsis:

• A short ellipsis: StoryWeaver travels a short distance or restart the same level (music doesn't fade).
• A long ellipsis. StoryWeaver travels a long distance (music fades).

We could also defer solving this until we redesign how the world fits together geographically. Maybe that cutscene at the end would become a playable scene with an opening line of dialogue, and then the player can walk off.

We could work around this by making the AudioStream resource in Fray's End unique so that it is a different object and the fade is applied… :D

[wjt]

I didn't solve the cutscene → fray's end problem for now.