From 2eba5e72b39382ad8762ea1bd0d5b010167ec5da Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Thu, 19 Nov 2026 10:44:02 +0700 Subject: [PATCH] refactor(native N-MOD-17): compensate live metadata edits and persist Player preferences atomically --- .../player/PlayerLiveMetadataCommitPolicy.h | 29 ++++ src/Main.cpp | 125 +++++++++++------- ...ve_caption_wire_geometry_contract.test.cjs | 11 +- tests/player_setlist_archive_test.cpp | 35 +++++ 4 files changed, 152 insertions(+), 48 deletions(-) create mode 100644 engine/player/PlayerLiveMetadataCommitPolicy.h diff --git a/engine/player/PlayerLiveMetadataCommitPolicy.h b/engine/player/PlayerLiveMetadataCommitPolicy.h new file mode 100644 index 000000000..ccaa424a5 --- /dev/null +++ b/engine/player/PlayerLiveMetadataCommitPolicy.h @@ -0,0 +1,29 @@ +// SPDX-License-Identifier: AGPL-3.0-only +#pragma once + +// N-MOD-17: compensation policy for durable Player metadata writes on the +// JUCE CONTROL thread. The existing LiveAudioEngine remains the sole deck +// owner. Native acceptance precedes disk I/O for responsive live KEY/TEMPO +// and Cue gestures; failed persistence attempts the exact previous values. +// An unrecoverable native rollback is handled by the caller's safe stop. +namespace armix::player { +struct PlayerLiveMetadataCommitPolicy final { + enum class Outcome { + accepted, + nativeRejected, + saveRejectedRecovered, + saveRejectedRollbackFailed + }; + template + static Outcome run(bool requiresNative,ApplyNative&& apply, + Save&& save,RestoreNative&& restore) { + // Editing NEXT is metadata only. No native/PCM DSP mutation happens. + if(!requiresNative) + return save()?Outcome::accepted:Outcome::saveRejectedRecovered; + if(!apply())return Outcome::nativeRejected; + if(save())return Outcome::accepted; + return restore()?Outcome::saveRejectedRecovered: + Outcome::saveRejectedRollbackFailed; + } +}; +} // namespace armix::player diff --git a/src/Main.cpp b/src/Main.cpp index 7a04b6746..482b822c7 100644 --- a/src/Main.cpp +++ b/src/Main.cpp @@ -71,6 +71,7 @@ #include "../engine/player/PlayerShowEditPolicy.h" #include "../engine/player/PlayerShowTransitionPolicy.h" #include "../engine/player/PlayerCueEditPolicy.h" +#include "../engine/player/PlayerLiveMetadataCommitPolicy.h" #include "../engine/player/PlayerLibraryPolicy.h" #include #include @@ -3885,15 +3886,6 @@ class ConsoleWindow final : public juce::DocumentWindow, private juce::Timer, pr // Versioned setlist v3. Song paths remain external and are NEVER moved, // deleted or copied by editing a show. v1/v2 migrate non-destructively. - void saveActivePlayerSet() { - if(playerSets_.empty())playerSets_.push_back({"My Setlist",{},{}}); - if(playerActiveSet_<0 || - playerActiveSet_>=static_cast(playerSets_.size())) - playerActiveSet_=0; - auto& active=playerSets_[static_cast(playerActiveSet_)]; - active.files=playerLibrary_; - active.controls=playerTrackSettings_; - } void activatePlayerSet(int index) { if(index<0 || index>=static_cast(playerSets_.size()))return; playerActiveSet_=index; @@ -3932,33 +3924,49 @@ class ConsoleWindow final : public juce::DocumentWindow, private juce::Timer, pr playerAutoNext_=parsed.autoNext; playerFadeMilliseconds_=parsed.fadeMs; } - void persistPlayerLibrary() { - saveActivePlayerSet(); - const auto result=armix::player::PlayerSetlistRepository::save( - settingsDirectory().getChildFile("player-library.json"), - playerSets_,playerActiveSet_,playerAutoNext_,playerFadeMilliseconds_); - if(result==armix::player::PlayerSetlistRepository::SaveStatus::invalidState) - playerError_="Unable to save setlists; invalid setlist state"; - else if(result==armix::player::PlayerSetlistRepository::SaveStatus::ioError) - playerError_="Unable to save setlists; check folder permissions"; - } - bool commitPlayerTrackEdit(std::vector nextFiles, - std::vector nextControls) { + bool commitPlayerMetadata(std::vector nextFiles, + std::vector nextControls, + bool nextAutoNext,int nextFadeMs) { using Edit=armix::player::PlayerSetlistEditTransaction; auto outcome=Edit::replaceActiveTracks( settingsDirectory().getChildFile("player-library.json"), playerSets_,playerActiveSet_,nextFiles,nextControls, - playerAutoNext_,playerFadeMilliseconds_); + nextAutoNext,nextFadeMs); if(!outcome.committed()) { playerError_=outcome.error; return false; } - // No accepted Player identity/queue/index change precedes disk commit. + // File acceptance comes before EVERY durable in-memory mutation. playerSets_=std::move(outcome.sets); playerLibrary_=std::move(nextFiles); playerTrackSettings_=std::move(nextControls); + playerAutoNext_=nextAutoNext; + playerFadeMilliseconds_=nextFadeMs; return true; } + bool commitPlayerTrackEdit(std::vector nextFiles, + std::vector nextControls) { + return commitPlayerMetadata(std::move(nextFiles), + std::move(nextControls),playerAutoNext_,playerFadeMilliseconds_); + } + bool commitPlayerPreferences(bool nextAutoNext,int nextFadeMs) { + return commitPlayerMetadata(playerLibrary_,playerTrackSettings_, + nextAutoNext,nextFadeMs); + } + void stopPlayerAfterUnrecoveredMetadata() { + // Persist rejected AND native restore rejected. Never leave an + // unrecorded live deck applying controls different from the setlist. + if(playerPendingIndex_>=0)playerQueueEpoch_.changed(); + engine_.playerStop(); + playerCurrent_=-1; + playerPendingIndex_=-1; + playerPendingQueueFile_={}; + playerOutputPendingIndex_=-1; + playerLoopCurrent_=false; + playerAutoAdvanceGate_.rearm(); + playerError_="Could not save song settings or restore native playback; " + "Player stopped to keep setlist safe"; + } bool playerShowMaySwitchSet() { const auto state=engine_.playerStatus().getProperty("state","").toString(); if(state=="PLAYING" || state=="PREPARING" || state=="PAUSED") { @@ -4584,17 +4592,25 @@ class ConsoleWindow final : public juce::DocumentWindow, private juce::Timer, pr else if(direction==1 || direction==-1) next.tempo=std::clamp(next.tempo+direction*5,80,120); else return; // invalid native control intent cannot mutate DSP - // A performer must be able to tune NEXT while CURRENT is - // playing without changing CURRENT audio. Only send live DSP - // commands for the currently loaded song. - if(!target.updateLiveDeck || - engine_.setPlayerPitchTempo(next.key,next.tempo)) { - playerTrackSettings_[static_cast(i)]=next; + // NEXT changes persist without touching CURRENT audio. For a + // loaded CURRENT, use native-first acceptance, durable Save and + // compensation on failure; never publish unsaved track state. + using NativeMeta=armix::player::PlayerLiveMetadataCommitPolicy; + const auto previous=playerTrackSettings_[static_cast(i)]; + auto staged=playerTrackSettings_; + staged[static_cast(i)]=next; + const auto outcome=NativeMeta::run( + target.updateLiveDeck, + [&]{return engine_.setPlayerPitchTempo(next.key,next.tempo);}, + [&]{return commitPlayerTrackEdit(playerLibrary_,std::move(staged));}, + [&]{return engine_.setPlayerPitchTempo(previous.key,previous.tempo);}); + if(outcome==NativeMeta::Outcome::accepted) playerError_.clear(); - persistPlayerLibrary(); - emitPlayerState(true); - } - return; + else if(outcome==NativeMeta::Outcome::nativeRejected) + playerError_="Unable to apply native KEY or TEMPO"; + else if(outcome==NativeMeta::Outcome::saveRejectedRollbackFailed) + stopPlayerAfterUnrecoveredMetadata(); + emitPlayerState(true);return; } if(action=="playerLoopToggle") { const bool enable=value.isBool() && static_cast(value); @@ -4628,7 +4644,7 @@ class ConsoleWindow final : public juce::DocumentWindow, private juce::Timer, pr playerError_="Select the playing song to edit its cue"; emitPlayerState();return; } - auto& cues=playerTrackSettings_[static_cast( + const auto cues=playerTrackSettings_[static_cast( playerCurrent_)]; const auto transport=engine_.playerStatus(); const double now=static_cast( @@ -4658,20 +4674,32 @@ class ConsoleWindow final : public juce::DocumentWindow, private juce::Timer, pr "OUT must be after IN":"Invalid song cue marker"; emitPlayerState();return; } - // Deck admission FIRST. Failed or invalid edits must never - // poison the persisted v3 archive or the WebView readback. - if(!engine_.setPlayerCueRange(nextCue->in,nextCue->out)) { + // Native admission FIRST (as before); stage the proposed + // archive edit, and restore the previous accepted cue if the + // durable Save rejects. Never mutate the live control vector + // until both native and disk accepted the candidate. + using NativeMeta=armix::player::PlayerLiveMetadataCommitPolicy; + auto staged=playerTrackSettings_; + staged[static_cast(playerCurrent_)].cueIn=nextCue->in; + staged[static_cast(playerCurrent_)].cueOut=nextCue->out; + const auto outcome=NativeMeta::run(true, + [&]{return engine_.setPlayerCueRange(nextCue->in,nextCue->out);}, + [&]{return commitPlayerTrackEdit(playerLibrary_,std::move(staged));}, + [&]{return engine_.setPlayerCueRange(cues.cueIn,cues.cueOut);}); + if(outcome==NativeMeta::Outcome::nativeRejected) { playerError_="Could not update native song markers"; emitPlayerState();return; } - cues.cueIn=nextCue->in; - cues.cueOut=nextCue->out; + if(outcome==NativeMeta::Outcome::saveRejectedRollbackFailed) + stopPlayerAfterUnrecoveredMetadata(); + if(outcome!=NativeMeta::Outcome::accepted) { + emitPlayerState(true);return; + } if(playerLoopCurrent_ && !armix::player::PlayerShowTransitionPolicy::validLoop( - cues.cueIn,cues.cueOut,playerFadeMilliseconds_)) + nextCue->in,nextCue->out,playerFadeMilliseconds_)) playerLoopCurrent_=false; - playerError_.clear();persistPlayerLibrary(); - emitPlayerState(true);return; + playerError_.clear();emitPlayerState(true);return; } if(action=="playerPlay")return playTransportMusic(); if(action=="playerSeek") { @@ -4704,14 +4732,19 @@ class ConsoleWindow final : public juce::DocumentWindow, private juce::Timer, pr return playNextMusic(); } if(action=="playerAutoNext") { + const bool next=value.isBool() && static_cast(value); + if(!commitPlayerPreferences(next,playerFadeMilliseconds_)) { + emitPlayerState(true);return; + } playerAutoAdvanceGate_.rearm(); - playerAutoNext_=value.isBool() && static_cast(value); - persistPlayerLibrary();emitPlayerState(true);return; + playerError_.clear();emitPlayerState(true);return; } if(action=="playerFadeMs") { const int ms=static_cast(value); if(ms!=0 && ms!=180 && ms!=500 && ms!=1500)return; - playerFadeMilliseconds_=ms; + if(!commitPlayerPreferences(playerAutoNext_,ms)) { + emitPlayerState();return; + } if(playerLoopCurrent_ && playerCurrent_>=0 && playerCurrent_(playerTrackSettings_.size())) { const auto cue=playerTrackSettings_[ @@ -4720,7 +4753,7 @@ class ConsoleWindow final : public juce::DocumentWindow, private juce::Timer, pr cue.cueIn,cue.cueOut,ms)) playerLoopCurrent_=false; } - persistPlayerLibrary();emitPlayerState();return; + playerError_.clear();emitPlayerState();return; } if(action=="playerSelect" || action=="playerPlayNow") { const int i=static_cast(value); diff --git a/tests/native_caption_wire_geometry_contract.test.cjs b/tests/native_caption_wire_geometry_contract.test.cjs index 862d57ae5..6cc940a77 100644 --- a/tests/native_caption_wire_geometry_contract.test.cjs +++ b/tests/native_caption_wire_geometry_contract.test.cjs @@ -150,7 +150,13 @@ assert.match(playerRepository, /class PlayerSetlistRepository final/); assert.match(playerRepository, /juce::TemporaryFile staging\(target\)/); assert.match(playerRepository, /overwriteTargetFileWithTemporary\(\)/); assert.match(main, /PlayerSetlistRepository::load/); -assert.match(main, /PlayerSetlistRepository::save/); +assert.doesNotMatch(main, /PlayerSetlistRepository::save/); +assert.doesNotMatch(main, /void persistPlayerLibrary\(\)/); +assert.match(main, /commitPlayerMetadata/); +const playerLiveCommit=read('engine/player/PlayerLiveMetadataCommitPolicy.h'); +assert.match(playerLiveCommit, /saveRejectedRollbackFailed/); +assert.match(main, /NativeMeta::run/); +assert.match(main, /stopPlayerAfterUnrecoveredMetadata/); const persistence=main.slice(main.indexOf('void restorePlayerLibrary()'), main.indexOf('bool playerShowMaySwitchSet()')); assert.doesNotMatch(persistence, @@ -162,8 +168,9 @@ assert.match(main, /CuePolicy::plan/); const cueAction=main.slice(main.indexOf('if(action=="playerCueIn"'), main.indexOf('if(action=="playerPlay")')); assert.ok(cueAction.indexOf('engine_.setPlayerCueRange(nextCue->in,nextCue->out)') >= 0); -assert.ok(cueAction.indexOf('cues.cueIn=nextCue->in') > +assert.ok(cueAction.indexOf('commitPlayerTrackEdit(playerLibrary_,std::move(staged))') > cueAction.indexOf('engine_.setPlayerCueRange(nextCue->in,nextCue->out)')); +assert.match(cueAction, /engine_\.setPlayerCueRange\(cues\.cueIn,cues\.cueOut\)/); assert.match(main, /action=="playerKeyStep" \|\| action=="playerTempoStep"/); assert.match(main, /setPlayerPitchTempo\(next\.key,next\.tempo\)/); assert.match(playerHtml, /id="playerKeyMinus"/); diff --git a/tests/player_setlist_archive_test.cpp b/tests/player_setlist_archive_test.cpp index e41daed12..1c8079a35 100644 --- a/tests/player_setlist_archive_test.cpp +++ b/tests/player_setlist_archive_test.cpp @@ -8,6 +8,7 @@ #include "../src/PlayerSetlistArchive.h" #include "../src/PlayerSetlistRepository.h" #include "../src/PlayerSetlistEditTransaction.h" +#include "../engine/player/PlayerLiveMetadataCommitPolicy.h" using Archive=armix::player::PlayerSetlistArchive; using SavedSet=armix::player::PlayerSavedSet; @@ -351,6 +352,40 @@ int main() { failedTracks.status==Store::SaveStatus::ioError); assert(committedTracks.sets[0].files.size()==1); assert(transactionFile.loadFileAsString()==tracksBytes); + // N-MOD-17: preferences are saved on the same durable-first boundary. + // A rejected disk write cannot enable Auto Next or alter future fades. + const auto prefs=Edit::replaceActiveTracks( + transactionFile,committedTracks.sets,0,revisedFiles,revisedControls, + false,500); + assert(prefs.committed()); + const auto acceptedPrefs=Store::load(transactionFile); + assert(acceptedPrefs.document && !acceptedPrefs.document->autoNext); + assert(acceptedPrefs.document->fadeMs==500); + const auto prefsBytes=transactionFile.loadFileAsString(); + const auto failedPrefs=Edit::replaceActiveTracks( + blocked,prefs.sets,0,revisedFiles,revisedControls,true,1500); + assert(!failedPrefs.committed() && + failedPrefs.status==Store::SaveStatus::ioError); + assert(transactionFile.loadFileAsString()==prefsBytes); + + // Pure native+disk compensation sequencing. No JUCE audio device needed. + using Meta=armix::player::PlayerLiveMetadataCommitPolicy; + auto verifyMeta=[&](bool live,bool nativeOk,bool saveOk,bool rollbackOk, + Meta::Outcome expected,const char* order) { + std::string sequence; + const auto outcome=Meta::run(live, + [&]{sequence+='A';return nativeOk;}, + [&]{sequence+='S';return saveOk;}, + [&]{sequence+='R';return rollbackOk;}); + assert(outcome==expected && sequence==order); + }; + verifyMeta(false,false,true,false,Meta::Outcome::accepted,"S"); + verifyMeta(false,false,false,false,Meta::Outcome::saveRejectedRecovered,"S"); + verifyMeta(true,false,true,true,Meta::Outcome::nativeRejected,"A"); + verifyMeta(true,true,true,false,Meta::Outcome::accepted,"AS"); + verifyMeta(true,true,false,true,Meta::Outcome::saveRejectedRecovered,"ASR"); + verifyMeta(true,true,false,false, + Meta::Outcome::saveRejectedRollbackFailed,"ASR"); assert(sandbox.deleteRecursively()); // Legacy empty v3 content migrates to a non-destructive default setlist.