@quenty/soundplayer 1.0.1-canary.402.a911cda.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+## 1.0.1-canary.402.a911cda.0 (2023-08-23)
+
+
+### Bug Fixes
+
+* Remove unused code ([cb0e625](https://github.com/Quenty/NevermoreEngine/commit/cb0e62593e010fb6df9779f885e9abf9754f871c))
+
+
+### Features
+
+* Add sound layer playback system ([20ffe12](https://github.com/Quenty/NevermoreEngine/commit/20ffe12c1029f618ed689961ab5990c7da6855f7))

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2014-2023 James Onnen (Quenty)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+## SoundPlayer
+
+<div align="center">
+  <a href="http://quenty.github.io/NevermoreEngine/">
+    <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/docs.yml/badge.svg" alt="Documentation status" />
+  </a>
+  <a href="https://discord.gg/mhtGUS8">
+    <img src="https://img.shields.io/discord/385151591524597761?color=5865F2&label=discord&logo=discord&logoColor=white" alt="Discord" />
+  </a>
+  <a href="https://github.com/Quenty/NevermoreEngine/actions">
+    <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/build.yml/badge.svg" alt="Build and release status" />
+  </a>
+</div>
+
+Sound playback helper
+
+<div align="center"><a href="https://quenty.github.io/NevermoreEngine/api/LoopedSoundPlayer">View docs →</a></div>
+
+## Installation
+
+```
+npm install @quenty/soundplayer --save
+```

package/default.project.json

@@ -0,0 +1,6 @@
+{
+  "name": "soundplayer",
+  "tree": {
+    "$path": "src"
+  }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@quenty/soundplayer",
+  "version": "1.0.1-canary.402.a911cda.0",
+  "description": "Sound playback helper",
+  "keywords": [
+    "Roblox",
+    "Nevermore",
+    "Lua",
+    "soundplayer"
+  ],
+  "bugs": {
+    "url": "https://github.com/Quenty/NevermoreEngine/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Quenty/NevermoreEngine.git",
+    "directory": "src/soundplayer/"
+  },
+  "funding": {
+    "type": "patreon",
+    "url": "https://www.patreon.com/quenty"
+  },
+  "license": "MIT",
+  "contributors": [
+    "Quenty"
+  ],
+  "dependencies": {
+    "@quenty/adorneeutils": "3.1.0",
+    "@quenty/baseobject": "6.2.2-canary.402.a911cda.0",
+    "@quenty/blend": "6.26.1-canary.402.a911cda.0",
+    "@quenty/brio": "8.16.1-canary.402.a911cda.0",
+    "@quenty/instanceutils": "7.18.1-canary.402.a911cda.0",
+    "@quenty/loader": "6.2.2-canary.402.a911cda.0",
+    "@quenty/maid": "2.5.1-canary.402.a911cda.0",
+    "@quenty/numberrangeutils": "3.0.0",
+    "@quenty/promise": "6.7.1-canary.402.a911cda.0",
+    "@quenty/promisemaid": "1.2.1-canary.402.a911cda.0",
+    "@quenty/randomutils": "2.2.1-canary.402.a911cda.0",
+    "@quenty/rbxasset": "1.1.1-canary.402.a911cda.0",
+    "@quenty/rx": "7.14.1-canary.402.a911cda.0",
+    "@quenty/signal": "2.4.0",
+    "@quenty/sounds": "6.9.1-canary.402.a911cda.0",
+    "@quenty/table": "3.2.1-canary.402.a911cda.0",
+    "@quenty/transitionmodel": "1.17.1-canary.402.a911cda.0",
+    "@quenty/valueobject": "7.21.1-canary.402.a911cda.0",
+    "@quentystudios/t": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "a911cdaf4f1039b599528cec17b027f4660e4fd8"
+}

package/src/Client/Loops/Layered/LayeredLoopedSoundPlayer.lua

@@ -0,0 +1,169 @@
+--[=[
+	@class LayeredLoopedSoundPlayer
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local SpringTransitionModel = require("SpringTransitionModel")
+local ValueObject = require("ValueObject")
+local LoopedSoundPlayer = require("LoopedSoundPlayer")
+local Maid = require("Maid")
+local Rx = require("Rx")
+local SoundUtils = require("SoundUtils")
+local SoundLoopScheduleUtils = require("SoundLoopScheduleUtils")
+
+local LayeredLoopedSoundPlayer = setmetatable({}, SpringTransitionModel)
+LayeredLoopedSoundPlayer.ClassName = "LayeredLoopedSoundPlayer"
+LayeredLoopedSoundPlayer.__index = LayeredLoopedSoundPlayer
+
+function LayeredLoopedSoundPlayer.new(soundParent)
+	local self = setmetatable(SpringTransitionModel.new(), LayeredLoopedSoundPlayer)
+
+	self._soundParent = ValueObject.new(nil)
+	self._maid:GiveTask(self._soundParent)
+
+	self._bpm = ValueObject.new(nil)
+	self._maid:GiveTask(self._bpm)
+
+	self._defaultCrossFadeTime = ValueObject.new(0.5, "number")
+	self._maid:GiveTask(self._defaultCrossFadeTime)
+
+	self._layerMaid = Maid.new()
+	self._maid:GiveTask(self._layerMaid)
+
+	self._volumeMultiplier = ValueObject.new(1, "number")
+	self._maid:GiveTask(self._volumeMultiplier)
+
+	self._layers = {}
+
+	if soundParent then
+		self:SetSoundParent(soundParent)
+	end
+
+	return self
+end
+
+function LayeredLoopedSoundPlayer:SetDefaultCrossFadeTime(crossFadeTime)
+	return self._defaultCrossFadeTime:Mount(crossFadeTime)
+end
+
+function LayeredLoopedSoundPlayer:SetVolumeMultiplier(volumeMultiplier)
+	self._volumeMultiplier.Value = volumeMultiplier
+end
+
+function LayeredLoopedSoundPlayer:SetBPM(bpm)
+	assert(type(bpm) == "number" or bpm == nil, "Bad bpm")
+
+	self._bpm.Value = bpm
+end
+
+function LayeredLoopedSoundPlayer:SetSoundParent(soundParent)
+	self._soundParent.Value = soundParent
+end
+
+function LayeredLoopedSoundPlayer:Swap(layerId, soundId, scheduleOptions)
+	assert(type(layerId) == "string", 'Bad layerId')
+	assert(SoundUtils.isConvertableToRbxAsset(soundId) or soundId == nil, "Bad soundId")
+	assert(SoundLoopScheduleUtils.isLoopedSchedule(scheduleOptions) or scheduleOptions == nil, "Bad scheduleOptions")
+
+	local layer = self:_getOrCreateLayer(layerId)
+	layer:Swap(soundId, scheduleOptions)
+end
+
+function LayeredLoopedSoundPlayer:SwapOnLoop(layerId, soundId, scheduleOptions)
+	assert(type(layerId) == "string", 'Bad layerId')
+	assert(SoundUtils.isConvertableToRbxAsset(soundId) or soundId == nil, "Bad soundId")
+
+	local layer = self:_getOrCreateLayer(layerId)
+	layer:SwapOnLoop(soundId, scheduleOptions)
+end
+
+function LayeredLoopedSoundPlayer:SwapToSamples(layerId, soundId, scheduleOptions)
+	assert(type(layerId) == "string", 'Bad layerId')
+	assert(SoundUtils.isConvertableToRbxAsset(soundId) or soundId == nil, "Bad soundId")
+	assert(SoundLoopScheduleUtils.isLoopedSchedule(scheduleOptions) or scheduleOptions == nil, "Bad scheduleOptions")
+
+	local layer = self:_getOrCreateLayer(layerId)
+	layer:SwapToSamples(soundId, scheduleOptions)
+end
+
+function LayeredLoopedSoundPlayer:SwapToChoice(layerId, soundIdList, scheduleOptions)
+	assert(type(layerId) == "string", 'Bad layerId')
+	assert(type(soundIdList) == "table", "Bad soundIdList")
+	assert(SoundLoopScheduleUtils.isLoopedSchedule(scheduleOptions) or scheduleOptions == nil, "Bad scheduleOptions")
+
+	local layer = self:_getOrCreateLayer(layerId)
+	layer:SwapToChoice(soundIdList, scheduleOptions)
+end
+
+function LayeredLoopedSoundPlayer:PlayOnce(layerId, soundIdList, scheduleOptions)
+	assert(type(layerId) == "string", 'Bad layerId')
+	assert(type(soundIdList) == "table", "Bad soundIdList")
+	assert(SoundLoopScheduleUtils.isLoopedSchedule(scheduleOptions) or scheduleOptions == nil, "Bad scheduleOptions")
+
+	local layer = self:_getOrCreateLayer(layerId)
+	layer:PlayOnce(soundIdList, scheduleOptions)
+end
+
+function LayeredLoopedSoundPlayer:PlayOnceOnLoop(layerId, soundId, scheduleOptions)
+	assert(type(layerId) == "string", 'Bad layerId')
+
+	local layer = self:_getOrCreateLayer(layerId)
+	layer:PlayOnceOnLoop(soundId, scheduleOptions)
+end
+
+function LayeredLoopedSoundPlayer:_getOrCreateLayer(layerId)
+	if 	self._layers[layerId] then
+		return self._layers[layerId]
+	end
+
+	local maid = Maid.new()
+
+	local layer = LoopedSoundPlayer.new()
+	layer:SetDoSyncSoundPlayback(true)
+	maid:GiveTask(layer)
+
+	maid:GiveTask(layer:SetCrossFadeTime(self._defaultCrossFadeTime:Observe()))
+
+	maid:GiveTask(self._bpm:Observe():Subscribe(function(bpm)
+		layer:SetBPM(bpm)
+	end))
+
+	maid:GiveTask(self:ObserveVisible():Subscribe(function(isVisible, doNotAnimate)
+		layer:SetVisible(isVisible, doNotAnimate)
+	end))
+
+	maid:GiveTask(self._soundParent:Observe():Subscribe(function(parent)
+		layer:SetSoundParent(parent)
+	end))
+
+	maid:GiveTask(Rx.combineLatest({
+		visible = self:ObserveRenderStepped();
+		multiplier = self._volumeMultiplier:Observe();
+	}):Subscribe(function(state)
+		layer:SetVolumeMultiplier(state.multiplier*state.visible)
+	end))
+
+	self._layers[layerId] = layer
+	maid:GiveTask(function()
+		if self._layers[layerId] == layer then
+			self._layers[layerId] = nil
+		end
+	end)
+
+	self._layerMaid[layerId] = maid
+
+	return layer
+end
+
+function LayeredLoopedSoundPlayer:StopLayer(layerId)
+	assert(type(layerId) == "string", 'Bad layerId')
+
+	self._layerMaid[layerId] = nil
+end
+
+function LayeredLoopedSoundPlayer:StopAll()
+	self._layerMaid:DoCleaning()
+end
+
+return LayeredLoopedSoundPlayer

package/src/Client/Loops/Layered/LayeredLoopedSoundPlayer.story.lua

@@ -0,0 +1,160 @@
+--[[
+	@class LayeredLoopedSoundPlayer.story
+]]
+
+local require = require(game:GetService("ServerScriptService"):FindFirstChild("LoaderUtils", true).Parent).load(script)
+
+local Maid = require("Maid")
+local LayeredLoopedSoundPlayer = require("LayeredLoopedSoundPlayer")
+local Blend = require("Blend")
+
+return function(target)
+	local maid = Maid.new()
+
+	local layeredLoopedSoundPlayer = LayeredLoopedSoundPlayer.new()
+	layeredLoopedSoundPlayer:SetSoundParent(target)
+	layeredLoopedSoundPlayer:SetBPM(95)
+	maid:GiveTask(layeredLoopedSoundPlayer)
+
+	local function initial()
+		layeredLoopedSoundPlayer:SwapToChoice("drums", {
+			{
+				SoundId = "rbxassetid://14478151709";
+				Volume = 0.1;
+			};
+			{
+				SoundId = "rbxassetid://14478738244";
+				Volume = 0.1;
+			}
+		})
+		layeredLoopedSoundPlayer:SwapToChoice("rifts", {
+			{
+				SoundId = "rbxassetid://14478152812";
+				Volume = 0.2;
+			};
+			{
+				SoundId = "rbxassetid://14478729478";
+				Volume = 0.015;
+			};
+		})
+	end
+	initial()
+
+	layeredLoopedSoundPlayer:Show()
+
+	local function button(props)
+		return Blend.New "TextButton" {
+			Text = props.Text;
+			AutoButtonColor = true;
+			Font = Enum.Font.FredokaOne;
+			Size = UDim2.new(0, 100, 0, 30);
+
+			Blend.New "UICorner" {
+
+			};
+
+			[Blend.OnEvent "Activated"] = function()
+				props.OnActivated();
+			end;
+		};
+	end
+
+	maid:GiveTask(Blend.mount(target, {
+		Blend.New "Frame" {
+			Name = "ButtonContainer";
+			BackgroundTransparency = 1;
+			Position = UDim2.new(0.5, 0, 0, 5);
+			AnchorPoint = Vector2.new(0.5, 0);
+			Size = UDim2.new(1, 0, 0, 30);
+
+			Blend.New "UIListLayout" {
+				FillDirection = Enum.FillDirection.Horizontal;
+				Padding = UDim.new(0, 5);
+				HorizontalAlignment = Enum.HorizontalAlignment.Center;
+			};
+
+			button({
+				Text = "Toggle";
+				OnActivated = function()
+					layeredLoopedSoundPlayer:Toggle()
+				end;
+			});
+
+			button({
+				Text = "Reset";
+				OnActivated = function()
+					initial()
+				end;
+			});
+
+			button({
+				Text = "Combat equip";
+				OnActivated = function()
+					layeredLoopedSoundPlayer:SwapToChoice("drums", {
+						"rbxassetid://14478154829";
+						"rbxassetid://14478714545";
+						"rbxassetid://14478772830";
+						"rbxassetid://14478897865";
+					})
+					layeredLoopedSoundPlayer:PlayOnceOnLoop("rifts", nil)
+				end;
+			});
+
+			button({
+				Text = "On target lock";
+				OnActivated = function()
+					layeredLoopedSoundPlayer:SwapToChoice("drums", {
+						{
+							SoundId = "rbxassetid://14478150956";
+							Volume = 0.1;
+						};
+						{
+							SoundId = "rbxassetid://14478721669";
+							Volume = 0.2;
+						};
+						"rbxassetid://14478154829";
+						"rbxassetid://14478764914";
+					})
+
+					layeredLoopedSoundPlayer:SwapToChoice("rifts", {
+						"rbxassetid://14478145963";
+						"rbxassetid://14478156714";
+						{
+							SoundId = "rbxassetid://14478777472";
+							Volume = 0.1;
+						};
+						{
+							SoundId = "rbxassetid://14478793045";
+							Volume = 0.1;
+						};
+					})
+				end;
+			});
+
+			button({
+				Text = "On low health";
+				OnActivated = function()
+					layeredLoopedSoundPlayer:SwapToChoice("drums", {
+						"rbxassetid://14478746326";
+						"rbxassetid://14478767498";
+						"rbxassetid://14478797936"; -- record scratch
+					})
+
+				end;
+			});
+
+
+			button({
+				Text = "Target drop";
+				OnActivated = function()
+					layeredLoopedSoundPlayer:PlayOnceOnLoop("rifts", "rbxassetid://14478158396")
+				end;
+			});
+		}
+	}))
+
+
+	return function()
+		maid:DoCleaning()
+	end
+end

package/src/Client/Loops/LoopedSoundPlayer.lua

@@ -0,0 +1,449 @@
+--[=[
+	@class LoopedSoundPlayer
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local RunService = game:GetService("RunService")
+
+local Maid = require("Maid")
+local Promise = require("Promise")
+local PromiseMaidUtils = require("PromiseMaidUtils")
+local RandomSampler = require("RandomSampler")
+local RandomUtils = require("RandomUtils")
+local Rx = require("Rx")
+local RxInstanceUtils = require("RxInstanceUtils")
+local Signal = require("Signal")
+local SimpleLoopedSoundPlayer = require("SimpleLoopedSoundPlayer")
+local SoundLoopScheduleUtils = require("SoundLoopScheduleUtils")
+local SoundPromiseUtils = require("SoundPromiseUtils")
+local SoundUtils = require("SoundUtils")
+local SpringTransitionModel = require("SpringTransitionModel")
+local ValueObject = require("ValueObject")
+
+local LoopedSoundPlayer = setmetatable({}, SpringTransitionModel)
+LoopedSoundPlayer.ClassName = "LoopedSoundPlayer"
+LoopedSoundPlayer.__index = LoopedSoundPlayer
+
+function LoopedSoundPlayer.new(soundId, soundParent)
+	assert(SoundUtils.isConvertableToRbxAsset(soundId) or soundId == nil, "Bad soundId")
+
+	local self = setmetatable(SpringTransitionModel.new(), LoopedSoundPlayer)
+
+	self._currentSoundLooped = Signal.new()
+	self._maid:GiveTask(self._currentSoundLooped)
+
+	self._currentSoundLoopedAfterDelay = Signal.new()
+	self._maid:GiveTask(self._currentSoundLoopedAfterDelay)
+
+	self:SetSpeed(10)
+
+	self._bpm = ValueObject.new(nil)
+	self._maid:GiveTask(self._bpm)
+
+	self._soundParent = ValueObject.new(nil)
+	self._maid:GiveTask(self._soundParent)
+
+	self._crossFadeTime = ValueObject.new(0.5, "number")
+	self._maid:GiveTask(self._crossFadeTime)
+
+	self._volumeMultiplier = ValueObject.new(1, "number")
+	self._maid:GiveTask(self._volumeMultiplier)
+
+	self._doSyncSoundPlayback = ValueObject.new(false, "boolean")
+	self._maid:GiveTask(self._doSyncSoundPlayback)
+
+	self._currentActiveSound = ValueObject.new(nil)
+	self._maid:GiveTask(self._currentActiveSound)
+
+	self._currentSoundId = ValueObject.new(soundId)
+	self._maid:GiveTask(self._currentSoundId)
+
+	self._defaultScheduleOptions = SoundLoopScheduleUtils.default()
+
+	self._currentLoopSchedule = ValueObject.new(self._defaultScheduleOptions)
+	self._maid:GiveTask(self._currentLoopSchedule)
+
+	if soundParent then
+		self:SetSoundParent(soundParent)
+	end
+
+	if soundId then
+		self:Swap(soundId)
+	end
+
+	self:_setupRender()
+
+	return self
+end
+
+function LoopedSoundPlayer:SetCrossFadeTime(crossFadeTime)
+	return self._crossFadeTime:Mount(crossFadeTime)
+end
+
+function LoopedSoundPlayer:SetVolumeMultiplier(volume)
+	self._volumeMultiplier.Value = volume
+end
+
+function LoopedSoundPlayer:SetBPM(bpm)
+	assert(type(bpm) == "number" or bpm == nil, "Bad bpm")
+
+	self._bpm.Value = bpm
+end
+
+function LoopedSoundPlayer:SetSoundParent(parent)
+	self._soundParent.Value = parent
+end
+
+function LoopedSoundPlayer:Swap(soundId, loopSchedule)
+	assert(SoundUtils.isConvertableToRbxAsset(soundId) or soundId == nil, "Bad soundId")
+	loopSchedule = self:_convertToLoopedSchedule(loopSchedule)
+
+	local maid = Maid.new()
+
+	maid:GiveTask(self:_scheduleFirstPlay(loopSchedule, function()
+		self._currentLoopSchedule.Value = loopSchedule
+		self._currentSoundId.Value = soundId
+	end))
+
+	self._maid._swappingTo = maid
+end
+
+function LoopedSoundPlayer:SetDoSyncSoundPlayback(doSyncSoundPlayback)
+	self._doSyncSoundPlayback.Value = doSyncSoundPlayback
+end
+
+function LoopedSoundPlayer:_setupRender()
+	self._maid:GiveTask(self._currentSoundId:ObserveBrio(function(value)
+		return value ~= nil
+	end):Subscribe(function(brio)
+		if brio:IsDead() then
+			return
+		end
+
+
+		local maid = brio:ToMaid()
+		local soundId = brio:GetValue()
+
+		maid:GiveTask(self:_renderSoundPlayer(soundId))
+	end))
+end
+
+function LoopedSoundPlayer:_renderSoundPlayer(soundId)
+	local maid = Maid.new()
+
+	local renderMaid = Maid.new()
+	local soundPlayer = SimpleLoopedSoundPlayer.new(soundId)
+	soundPlayer:SetTransitionTime(self._crossFadeTime)
+	renderMaid:GiveTask(soundPlayer)
+
+	renderMaid:GiveTask(Rx.combineLatest({
+		bpm = self._bpm:Observe();
+		isLoaded = Rx.fromPromise(SoundPromiseUtils.promiseLoaded(soundPlayer.Sound));
+		doSyncSoundPlayback = self._doSyncSoundPlayback:Observe();
+		timeLength = RxInstanceUtils.observeProperty(soundPlayer.Sound, "TimeLength");
+	}):Subscribe(function(state)
+		local syncMaid = Maid.new()
+
+		if state.doSyncSoundPlayback then
+			if state.bpm then
+				local bps = state.bpm/60
+				local beatTime = 1/bps
+				local truncatedTimeLength = math.floor(state.timeLength/beatTime) * beatTime
+				local currentTimePosition = soundPlayer.Sound.TimePosition
+				local clockDistanceIntoBeat = os.clock() % beatTime
+				local soundDistanceIntoBeat = currentTimePosition % beatTime
+
+				-- Skip to next beat
+				local offset = (beatTime + (clockDistanceIntoBeat - soundDistanceIntoBeat)) % beatTime
+				soundPlayer.Sound.TimePosition = currentTimePosition + offset
+
+				syncMaid:GiveTask(RunService.RenderStepped:Connect(function()
+					if soundPlayer.Sound.TimePosition > truncatedTimeLength then
+						soundPlayer.Sound.TimePosition = soundPlayer.Sound.TimePosition % truncatedTimeLength
+
+						if self.Destroy then
+							if self._currentActiveSound.Value == soundPlayer.Sound then
+								self._currentSoundLooped:Fire()
+							end
+						end
+					end
+				end))
+			else
+				soundPlayer.Sound.TimePosition = os.clock() % state.timeLength
+			end
+		end
+
+		renderMaid._syncing = syncMaid
+	end))
+
+	maid:GiveTask(Rx.combineLatest({
+		loopSchedule = self._currentLoopSchedule:Observe();
+	}):Pipe({
+		Rx.throttleDefer();
+	}):Subscribe(function(state)
+		local scheduleMaid = Maid.new()
+
+		scheduleMaid:GiveTask(self:_setupLoopScheduling(soundPlayer, state.loopSchedule))
+
+		renderMaid._loopMaid = scheduleMaid
+	end))
+
+	maid:GiveTask(soundPlayer.Sound.DidLoop:Connect(function()
+		self._currentSoundLooped:Fire()
+	end))
+
+	self._currentActiveSound.Value = soundPlayer.Sound
+
+	maid:GiveTask(function()
+		if self._currentActiveSound.Value == soundPlayer.Sound then
+			self._currentActiveSound.Value = nil
+		end
+	end)
+
+	renderMaid:GiveTask(self._soundParent:Observe():Subscribe(function(parent)
+		soundPlayer.Sound.Parent = parent
+	end))
+
+	maid:GiveTask(Rx.combineLatest({
+		visible = self:ObserveRenderStepped();
+		multiplier = self._volumeMultiplier:Observe();
+	}):Subscribe(function(state)
+		soundPlayer:SetVolumeMultiplier(state.multiplier*state.visible)
+	end))
+
+	maid:GiveTask(self:ObserveVisible():Subscribe(function(isVisible, doNotAnimate)
+		soundPlayer:SetVisible(isVisible, doNotAnimate)
+	end))
+
+	maid:GiveTask(function()
+		soundPlayer:PromiseHide():Then(function()
+			renderMaid:Destroy()
+		end)
+	end)
+
+	return maid
+end
+
+function LoopedSoundPlayer:SetVolumeMultiplier(volume)
+	self._volumeMultiplier.Value = volume
+end
+
+function LoopedSoundPlayer:_setupLoopScheduling(soundPlayer, loopSchedule)
+	local maid = Maid.new()
+
+	if loopSchedule.maxLoops then
+		local loopCount = 0
+		maid:GiveTask(self._currentSoundLooped:Connect(function()
+			loopCount = loopCount + 1
+
+			-- Cancel
+			if loopCount > loopSchedule.maxLoops then
+				self._currentSoundId.Value = nil
+			end
+		end))
+	end
+
+	if loopSchedule.loopDelay then
+		maid:GiveTask(self._currentSoundLooped:Connect(function()
+			local waitTime = SoundLoopScheduleUtils.getWaitTimeSeconds(loopSchedule.loopDelay)
+
+			soundPlayer.Sound:Pause()
+
+			maid._scheduled = task.delay(waitTime, function()
+				self._currentSoundLoopedAfterDelay:Fire()
+				soundPlayer.Sound:Play()
+			end)
+		end))
+	else
+		maid:GiveTask(self._currentSoundLooped:Connect(function()
+			self._currentSoundLoopedAfterDelay:Fire()
+		end))
+	end
+
+	return maid
+end
+
+function LoopedSoundPlayer:SwapToSamples(soundIdList, loopSchedule)
+	assert(type(soundIdList) == "table", "Bad soundIdList")
+	loopSchedule = self:_convertToLoopedSchedule(loopSchedule)
+
+	local loopMaid = Maid.new()
+
+	loopMaid:GiveTask(self:_scheduleFirstPlay(loopSchedule, function()
+		local sampler = RandomSampler.new(soundIdList)
+		self._currentLoopSchedule.Value = loopSchedule
+		self._currentSoundId.Value = sampler:Sample()
+
+		loopMaid:GiveTask(self._currentSoundLoopedAfterDelay:Connect(function()
+			self._currentSoundId.Value = sampler:Sample()
+		end))
+	end))
+
+	self._maid._swappingTo = loopMaid
+end
+
+function LoopedSoundPlayer:SwapToChoice(soundIdList, loopSchedule)
+	assert(type(soundIdList) == "table", "Bad soundIdList")
+	loopSchedule = self:_convertToLoopedSchedule(loopSchedule)
+
+	local loopMaid = Maid.new()
+
+	loopMaid:GiveTask(self:_scheduleFirstPlay(loopSchedule, function()
+		self._currentLoopSchedule.Value = loopSchedule
+		self._currentSoundId.Value = RandomUtils.choice(soundIdList)
+
+		loopMaid:GiveTask(self._currentSoundLoopedAfterDelay:Connect(function()
+			self._currentSoundId.Value = RandomUtils.choice(soundIdList)
+		end))
+	end))
+
+	self._maid._swappingTo = loopMaid
+end
+
+function LoopedSoundPlayer:PlayOnce(soundId, loopSchedule)
+	assert(SoundUtils.isConvertableToRbxAsset(soundId) or soundId == nil, "Bad soundId")
+	loopSchedule = self:_convertToLoopedSchedule(loopSchedule)
+
+	self:Swap(soundId, SoundLoopScheduleUtils.maxLoops(1, loopSchedule))
+end
+
+function LoopedSoundPlayer:SwapOnLoop(soundId, loopSchedule)
+	assert(SoundUtils.isConvertableToRbxAsset(soundId) or soundId == nil, "Bad soundId")
+	loopSchedule = self:_convertToLoopedSchedule(loopSchedule)
+
+	self:Swap(soundId, SoundLoopScheduleUtils.onNextLoop(loopSchedule))
+end
+
+function LoopedSoundPlayer:PlayOnceOnLoop(soundId, loopSchedule)
+	assert(SoundUtils.isConvertableToRbxAsset(soundId) or soundId == nil, "Bad soundId")
+	loopSchedule = self:_convertToLoopedSchedule(loopSchedule)
+
+	self:PlayOnce(soundId, SoundLoopScheduleUtils.onNextLoop(loopSchedule))
+end
+
+function LoopedSoundPlayer:_convertToLoopedSchedule(loopSchedule)
+	assert(SoundLoopScheduleUtils.isLoopedSchedule(loopSchedule) or loopSchedule == nil, "Bad loopSchedule")
+	return loopSchedule or self._defaultScheduleOptions
+end
+
+function LoopedSoundPlayer:_scheduleFirstPlay(loopSchedule, callback)
+	assert(SoundLoopScheduleUtils.isLoopedSchedule(loopSchedule), "Bad loopSchedule")
+	assert(type(callback) == "function", "Bad callback")
+
+	local maid = Maid.new()
+
+	local observable = Rx.of(true)
+	if loopSchedule.playOnNextLoop then
+		observable = observable:Pipe({
+			Rx.switchMap(function()
+				local waitTime = nil
+				if loopSchedule.maxInitialWaitTimeForNextLoop then
+					waitTime = SoundLoopScheduleUtils.getWaitTimeSeconds(loopSchedule.maxInitialWaitTimeForNextLoop)
+				end
+
+				return self:_observeActiveSoundFinishLoop(waitTime)
+			end);
+		});
+	end
+
+	if loopSchedule.initialDelay then
+		observable = observable:Pipe({
+			Rx.switchMap(function()
+				return Rx.delayed(SoundLoopScheduleUtils.getWaitTimeSeconds(loopSchedule.initialDelay))
+			end);
+		});
+	end
+
+	-- Immediate
+	if observable then
+		maid._observeOnce = observable:Subscribe(function()
+			maid._observeOnce = nil
+			callback()
+		end)
+	else
+		callback()
+	end
+
+	return maid
+end
+
+function LoopedSoundPlayer:StopAfterLoop()
+	local swapMaid = Maid.new()
+
+	swapMaid:GiveTask(self._currentSoundLooped:Connect(function()
+		if self._maid._swappingTo == swapMaid then
+			self._currentSoundId.Value = nil
+		end
+	end))
+
+	self._maid._swappingTo = swapMaid
+end
+
+function LoopedSoundPlayer:_observeActiveSoundFinishLoop(maxWaitTime)
+	local startTime = os.clock()
+
+	return self._currentActiveSound:Observe():Pipe({
+		Rx.throttleDefer();
+		Rx.switchMap(function(sound)
+			if not sound then
+				return Rx.of(true)
+			end
+
+			return Rx.combineLatest({
+				timeLength = RxInstanceUtils.observeProperty(sound, "TimeLength");
+				timePosition = RxInstanceUtils.observeProperty(sound, "TimePosition");
+				crossFadeTime = self._crossFadeTime:Observe();
+			}):Pipe({
+				Rx.switchMap(function(state)
+					local timeElapsed = os.clock() - startTime
+					local timeRemaining
+					if maxWaitTime then
+						timeRemaining = maxWaitTime - timeElapsed
+					end
+
+					-- We assume it's gonna load
+					if state.timeLength == 0 then
+						if timeRemaining then
+							return Rx.delayed(timeRemaining)
+						else
+							return Rx.EMPTY
+						end
+					end
+
+					local waitTime = state.timeLength - state.timePosition - state.crossFadeTime
+
+					if timeRemaining then
+						waitTime = math.min(waitTime, timeRemaining)
+					end
+
+					return Rx.delayed(waitTime)
+				end);
+			})
+		end)
+	})
+end
+
+function LoopedSoundPlayer:PromiseLoopDone()
+	local promise = self._maid:GivePromise(Promise.new())
+
+	PromiseMaidUtils.whilePromise(promise, function(maid)
+		maid:GiveTask(self._currentSoundLooped:Connect(function()
+			promise:Resolve()
+		end))
+	end)
+
+	return promise
+end
+
+function LoopedSoundPlayer:PromiseSustain()
+	-- Never resolve (?)
+	return Promise.new()
+end
+
+
+function LoopedSoundPlayer:GetSound()
+	return self._sound
+end
+
+return LoopedSoundPlayer

package/src/Client/Loops/LoopedSoundPlayer.story.lua

@@ -0,0 +1,125 @@
+--[[
+	@class LoopedSoundPlayer.story
+]]
+
+local require = require(game:GetService("ServerScriptService"):FindFirstChild("LoaderUtils", true).Parent).load(script)
+
+local Maid = require("Maid")
+local LoopedSoundPlayer = require("LoopedSoundPlayer")
+local RandomUtils = require("RandomUtils")
+local Blend = require("Blend")
+local LoopedSoundScheduleUtils = require("LoopedSoundScheduleUtils")
+
+return function(target)
+	local maid = Maid.new()
+
+	local ORIGINAL = nil --"rbxassetid://14477435416"
+
+	local loopedSoundPlayer = LoopedSoundPlayer.new(ORIGINAL, target)
+	loopedSoundPlayer:SetDoSyncSoundPlayback(true)
+	loopedSoundPlayer:SetCrossFadeTime(2)
+	loopedSoundPlayer:SetVolumeMultiplier(0.25)
+	loopedSoundPlayer:SetSoundParent(target)
+	maid:GiveTask(loopedSoundPlayer)
+
+	local OPTIONS = {
+		"rbxassetid://14477453689";
+	}
+
+	maid:GiveTask(task.spawn(function()
+		while true do
+			task.wait(2)
+			-- loopedSoundPlayer:Swap(RandomUtils.choice(OPTIONS))
+		end
+	end))
+
+	loopedSoundPlayer:Show()
+
+	local function button(props)
+		return Blend.New "TextButton" {
+			Text = props.Text;
+			AutoButtonColor = true;
+			Font = Enum.Font.FredokaOne;
+			Size = UDim2.new(0, 100, 0, 30);
+
+			Blend.New "UICorner" {
+
+			};
+
+			[Blend.OnEvent "Activated"] = function()
+				props.OnActivated();
+			end;
+		};
+	end
+
+	maid:GiveTask(Blend.mount(target, {
+		Blend.New "Frame" {
+			Name = "ButtonContainer";
+			BackgroundTransparency = 1;
+			Position = UDim2.new(0.5, 0, 0, 5);
+			AnchorPoint = Vector2.new(0.5, 0);
+			Size = UDim2.new(1, 0, 0, 30);
+
+			Blend.New "UIListLayout" {
+				FillDirection = Enum.FillDirection.Horizontal;
+				Padding = UDim.new(0, 5);
+				HorizontalAlignment = Enum.HorizontalAlignment.Center;
+			};
+
+			button({
+				Text = "Toggle";
+				OnActivated = function()
+					loopedSoundPlayer:Toggle()
+				end;
+			});
+
+			button({
+				Text = "Reset";
+				OnActivated = function()
+					loopedSoundPlayer:Swap(ORIGINAL)
+				end;
+			});
+
+			button({
+				Text = "Swap sample";
+				OnActivated = function()
+					loopedSoundPlayer:SwapToSamples({
+						"rbxassetid://14478670277";
+						"rbxassetid://14478671494";
+						"rbxassetid://14478672676";
+					})
+				end;
+			});
+
+			button({
+				Text = "Play once";
+				OnActivated = function()
+					loopedSoundPlayer:PlayOnce("rbxassetid://14478764914")
+				end;
+			});
+
+			button({
+				Text = "Play delayed loop";
+				OnActivated = function()
+					loopedSoundPlayer:Swap({
+						SoundId ="rbxassetid://6052547865";
+						Volume = 3;
+					}, LoopedSoundScheduleUtils.schedule({
+						loopDelay = NumberRange.new(0.25, 1);
+					}))
+				end;
+			});
+
+			button({
+				Text = "Swap on loop";
+				OnActivated = function()
+					loopedSoundPlayer:SwapOnLoop(RandomUtils.choice(OPTIONS))
+				end;
+			});
+		}
+	}))
+
+	return function()
+		maid:DoCleaning()
+	end
+end

package/src/Client/Loops/SimpleLoopedSoundPlayer.lua

@@ -0,0 +1,63 @@
+--[=[
+	@class SimpleLoopedSoundPlayer
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local TimedTransitionModel = require("TimedTransitionModel")
+local Rx = require("Rx")
+local SoundUtils = require("SoundUtils")
+local SoundPromiseUtils = require("SoundPromiseUtils")
+local Promise = require("Promise")
+local ValueObject = require("ValueObject")
+
+local SimpleLoopedSoundPlayer = setmetatable({}, TimedTransitionModel)
+SimpleLoopedSoundPlayer.ClassName = "SimpleLoopedSoundPlayer"
+SimpleLoopedSoundPlayer.__index = SimpleLoopedSoundPlayer
+
+function SimpleLoopedSoundPlayer.new(soundId)
+	local self = setmetatable(TimedTransitionModel.new(), SimpleLoopedSoundPlayer)
+
+	self.Sound = SoundUtils.createSoundFromId(soundId)
+	self.Sound.Looped = true
+	self.Sound.Archivable = false
+	self._maid:GiveTask(self.Sound)
+
+	self:SetTransitionTime(1)
+
+	self._volumeMultiplier = ValueObject.new(1, "number")
+	self._maid:GiveTask(self._volumeMultiplier)
+
+	self._maxVolume = self.Sound.Volume
+
+	self._maid:GiveTask(Rx.combineLatest({
+		visible = self:ObserveRenderStepped();
+		multiplier = self._volumeMultiplier:Observe();
+	}):Subscribe(function(state)
+		self.Sound.Volume = state.visible*self._maxVolume*state.multiplier
+	end))
+
+	self._maid:GiveTask(self.VisibleChanged:Connect(function(isVisible)
+		if isVisible then
+			self.Sound:Play()
+		end
+	end))
+
+	return self
+end
+
+function SimpleLoopedSoundPlayer:SetVolumeMultiplier(volume)
+	self._volumeMultiplier.Value = volume
+end
+
+function SimpleLoopedSoundPlayer:PromiseSustain()
+	-- Never resolve
+	return Promise.new()
+end
+
+function SimpleLoopedSoundPlayer:PromiseLoopDone()
+	return SoundPromiseUtils.promiseLooped(self.Sound)
+end
+
+
+return SimpleLoopedSoundPlayer

package/src/Client/Loops/SimpleLoopedSoundPlayer.story.lua

@@ -0,0 +1,68 @@
+--[[
+	@class SimpleLoopedSoundPlayer.story
+]]
+
+local require = require(game:GetService("ServerScriptService"):FindFirstChild("LoaderUtils", true).Parent).load(script)
+
+local Maid = require("Maid")
+local ServiceBag = require("ServiceBag")
+local SimpleLoopedSoundPlayer = require("SimpleLoopedSoundPlayer")
+local Blend = require("Blend")
+
+return function(target)
+	local maid = Maid.new()
+	local serviceBag = ServiceBag.new()
+	maid:GiveTask(serviceBag)
+
+	local simpleLoopedSoundPlayer = SimpleLoopedSoundPlayer.new("rbxassetid://14477453689")
+	simpleLoopedSoundPlayer:SetTransitionTime(1)
+	maid:GiveTask(simpleLoopedSoundPlayer)
+
+	simpleLoopedSoundPlayer.Sound.Parent = target
+
+	simpleLoopedSoundPlayer:Show()
+
+	local function button(props)
+		return Blend.New "TextButton" {
+			Text = props.Text;
+			AutoButtonColor = true;
+			Font = Enum.Font.FredokaOne;
+			Size = UDim2.new(0, 100, 0, 30);
+
+			Blend.New "UICorner" {
+
+			};
+
+			[Blend.OnEvent "Activated"] = function()
+				props.OnActivated();
+			end;
+		};
+	end
+
+	maid:GiveTask(Blend.mount(target, {
+		Blend.New "Frame" {
+			Name = "ButtonContainer";
+			BackgroundTransparency = 1;
+			Position = UDim2.new(0.5, 0, 0, 5);
+			AnchorPoint = Vector2.new(0.5, 0);
+			Size = UDim2.new(1, 0, 0, 30);
+
+			Blend.New "UIListLayout" {
+				FillDirection = Enum.FillDirection.Horizontal;
+				Padding = UDim.new(0, 5);
+				HorizontalAlignment = Enum.HorizontalAlignment.Center;
+			};
+
+			button({
+				Text = "Toggle";
+				OnActivated = function()
+					simpleLoopedSoundPlayer:Toggle()
+				end;
+			});
+		}
+	}))
+
+	return function()
+		maid:DoCleaning()
+	end
+end

package/src/Client/Schedule/SoundLoopScheduleUtils.lua

@@ -0,0 +1,64 @@
+--[=[
+	@class SoundLoopScheduleUtils
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local t = require("t")
+local NumberRangeUtils = require("NumberRangeUtils")
+local Table = require("Table")
+
+local SoundLoopScheduleUtils = {}
+
+function SoundLoopScheduleUtils.schedule(loopedSchedule)
+	assert(SoundLoopScheduleUtils.isLoopedSchedule(loopedSchedule))
+
+	return table.freeze(loopedSchedule)
+end
+
+function SoundLoopScheduleUtils.onNextLoop(loopedSchedule)
+assert(SoundLoopScheduleUtils.isLoopedSchedule(loopedSchedule) or loopedSchedule == nil, "Bad loopedSchedule")
+
+	loopedSchedule = loopedSchedule or {}
+	return SoundLoopScheduleUtils.schedule(Table.merge(loopedSchedule, {
+		playOnNextLoop = true;
+	}))
+end
+
+function SoundLoopScheduleUtils.maxLoops(maxLoops, loopedSchedule)
+	assert(type(maxLoops) == "number", "Bad maxLoops")
+	assert(SoundLoopScheduleUtils.isLoopedSchedule(loopedSchedule) or loopedSchedule == nil, "Bad loopedSchedule")
+
+	loopedSchedule = loopedSchedule or {}
+	return SoundLoopScheduleUtils.schedule(Table.merge(loopedSchedule, {
+		maxLoops = maxLoops;
+	}))
+end
+
+function SoundLoopScheduleUtils.default()
+	return SoundLoopScheduleUtils.schedule({})
+end
+
+SoundLoopScheduleUtils.isWaitTimeSeconds = t.union(t.number, t.NumberRange)
+
+SoundLoopScheduleUtils.isLoopedSchedule = t.interface({
+	playOnNextLoop = t.optional(t.boolean);
+	maxLoops = t.optional(t.number);
+	initialDelay = t.optional(SoundLoopScheduleUtils.isWaitTimeSeconds);
+	loopDelay = t.optional(SoundLoopScheduleUtils.isWaitTimeSeconds);
+	maxInitialWaitTimeForNextLoop = t.optional(SoundLoopScheduleUtils.isWaitTimeSeconds);
+})
+
+function SoundLoopScheduleUtils.getWaitTimeSeconds(waitTime)
+	assert(SoundLoopScheduleUtils.isWaitTimeSeconds(waitTime))
+
+	if type(waitTime) == "number" then
+		return waitTime
+	elseif typeof(waitTime) == "NumberRange" then
+		return NumberRangeUtils.getValue(waitTime, math.random())
+	else
+		error("Bad waitTime")
+	end
+end
+
+return SoundLoopScheduleUtils

package/src/node_modules.project.json

@@ -0,0 +1,7 @@
+{
+  "name": "node_modules",
+  "globIgnorePaths": [ "**/.package-lock.json" ],
+  "tree": {
+    "$path": { "optional": "../node_modules" }
+  }
+}

package/test/default.project.json

@@ -0,0 +1,11 @@
+{
+  "name": "SoundPlayerTest",
+  "tree": {
+    "$className": "DataModel",
+    "ServerScriptService": {
+      "soundplayer": {
+        "$path": ".."
+      }
+    }
+  }
+}