@quenty/soundplayer 7.25.0 → 7.25.1

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [7.25.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/soundplayer@7.25.0...@quenty/soundplayer@7.25.1) (2026-01-05)
+
+
+### Bug Fixes
+
+* Add typing to SoundPlayer ([a7e538e](https://github.com/Quenty/NevermoreEngine/commit/a7e538eddcb002327c1fdff4e2a60c769f0a1ba5))
+* Update the sound group package to include sound volume multipliers ([bf9591f](https://github.com/Quenty/NevermoreEngine/commit/bf9591fe2d08dbefae47f8c449b7bbf20c01fdfe))
+
+
+
+
+
 # [7.25.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/soundplayer@7.24.4...@quenty/soundplayer@7.25.0) (2026-01-04)
 
 **Note:** Version bump only for package @quenty/soundplayer

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2014-2025 James Onnen (Quenty)
+Copyright (c) 2014-2026 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/soundplayer",
-  "version": "7.25.0",
+  "version": "7.25.1",
   "description": "Sound playback helper",
   "keywords": [
     "Roblox",
@@ -27,7 +27,7 @@
   "dependencies": {
     "@quenty/adorneeutils": "^3.3.3",
     "@quenty/baseobject": "^10.9.1",
-    "@quenty/blend": "^12.23.0",
+    "@quenty/blend": "^12.23.1",
     "@quenty/brio": "^14.21.0",
     "@quenty/instanceutils": "^13.21.0",
     "@quenty/loader": "^10.9.1",
@@ -41,12 +41,12 @@
     "@quenty/signal": "^7.11.3",
     "@quenty/sounds": "^10.14.4",
     "@quenty/table": "^3.9.0",
-    "@quenty/transitionmodel": "^7.24.0",
-    "@quenty/valueobject": "^13.22.0",
+    "@quenty/transitionmodel": "^7.24.1",
+    "@quenty/valueobject": "^13.22.1",
     "@quentystudios/t": "^3.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "22144a14aa443a177ff307edd3813a838f8c1d5f"
+  "gitHead": "5232cd2c58ca0dcdf591dd8ae78995211da2f3e2"
 }

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

@@ -1,5 +1,9 @@
---!nonstrict
+--!strict
 --[=[
+	This class provides layered synchronized sound playback with looping and scheduling, which is useful for
+	implementing complex ambient soundscapes or music tracks that require multiple layers to be played in sync, for example,
+	constructed music that adapts to game states.
+
 	@class LayeredLoopedSoundPlayer
 ]=]
 
@@ -12,14 +16,35 @@ local SoundLoopScheduleUtils = require("SoundLoopScheduleUtils")
 local SoundUtils = require("SoundUtils")
 local SpringTransitionModel = require("SpringTransitionModel")
 local ValueObject = require("ValueObject")
-local t = require("t")
+local t: any = require("t")
 
 local LayeredLoopedSoundPlayer = setmetatable({}, SpringTransitionModel)
 LayeredLoopedSoundPlayer.ClassName = "LayeredLoopedSoundPlayer"
 LayeredLoopedSoundPlayer.__index = LayeredLoopedSoundPlayer
 
-function LayeredLoopedSoundPlayer.new(soundParent)
-	local self = setmetatable(SpringTransitionModel.new(), LayeredLoopedSoundPlayer)
+export type LayeredLoopedSoundPlayer =
+	typeof(setmetatable(
+		{} :: {
+			_layerMaid: Maid.Maid,
+			_soundParent: ValueObject.ValueObject<Instance?>,
+			_soundGroup: ValueObject.ValueObject<SoundGroup?>,
+			_bpm: ValueObject.ValueObject<number?>,
+			_defaultCrossFadeTime: ValueObject.ValueObject<number>,
+			_volumeMultiplier: ValueObject.ValueObject<number>,
+			_layers: { [string]: LoopedSoundPlayer.LoopedSoundPlayer },
+		},
+		{} :: typeof({ __index = LayeredLoopedSoundPlayer })
+	))
+	& SpringTransitionModel.SpringTransitionModel<number>
+
+--[=[
+	Constructs a new LayeredLoopedSoundPlayer.
+
+	@param soundParent Instance? -- Optional parent for sounds
+	@return LayeredLoopedSoundPlayer
+]=]
+function LayeredLoopedSoundPlayer.new(soundParent: Instance?): LayeredLoopedSoundPlayer
+	local self: LayeredLoopedSoundPlayer = setmetatable(SpringTransitionModel.new() :: any, LayeredLoopedSoundPlayer)
 
 	self._layerMaid = self._maid:Add(Maid.new())
 
@@ -38,29 +63,61 @@ function LayeredLoopedSoundPlayer.new(soundParent)
 	return self
 end
 
-function LayeredLoopedSoundPlayer:SetDefaultCrossFadeTime(crossFadeTime: ValueObject.Mountable<number>)
+--[=[
+	Sets the default cross fade time for the LayeredLoopedSoundPlayer.
+]=]
+function LayeredLoopedSoundPlayer.SetDefaultCrossFadeTime(
+	self: LayeredLoopedSoundPlayer,
+	crossFadeTime: ValueObject.Mountable<number>
+): () -> ()
 	return self._defaultCrossFadeTime:Mount(crossFadeTime)
 end
 
-function LayeredLoopedSoundPlayer:SetVolumeMultiplier(volumeMultiplier: ValueObject.Mountable<number>)
+--[=[
+	Sets the volume multiplier for the LayeredLoopedSoundPlayer.
+]=]
+function LayeredLoopedSoundPlayer.SetVolumeMultiplier(
+	self: LayeredLoopedSoundPlayer,
+	volumeMultiplier: ValueObject.Mountable<number>
+): () -> ()
 	return self._volumeMultiplier:Mount(volumeMultiplier)
 end
 
-function LayeredLoopedSoundPlayer:SetBPM(bpm: ValueObject.Mountable<number?>)
-	self._bpm.Value = bpm
+--[=[
+	Sets the BPM for syncing sound playback.
+]=]
+function LayeredLoopedSoundPlayer.SetBPM(self: LayeredLoopedSoundPlayer, bpm: ValueObject.Mountable<number?>): () -> ()
+	return self._bpm:Mount(bpm)
 end
 
-function LayeredLoopedSoundPlayer:SetSoundParent(soundParent: Instance?)
+--[=[
+	Sets the parent instance for the LayeredLoopedSoundPlayer.
+]=]
+function LayeredLoopedSoundPlayer.SetSoundParent(self: LayeredLoopedSoundPlayer, soundParent: Instance?): ()
 	assert(typeof(soundParent) == "Instance" or soundParent == nil, "Bad soundParent")
 
 	self._soundParent.Value = soundParent
 end
 
-function LayeredLoopedSoundPlayer:SetSoundGroup(soundGroup: SoundGroup?)
+--[=[
+	Sets the sound group for the LayeredLoopedSoundPlayer.
+]=]
+function LayeredLoopedSoundPlayer.SetSoundGroup(
+	self: LayeredLoopedSoundPlayer,
+	soundGroup: ValueObject.Mountable<SoundGroup?>
+): () -> ()
 	return self._soundGroup:Mount(soundGroup)
 end
 
-function LayeredLoopedSoundPlayer:Swap(layerId: string, soundId, scheduleOptions)
+--[=[
+	Swaps the layer to play the given sound on loop schedule.
+]=]
+function LayeredLoopedSoundPlayer.Swap(
+	self: LayeredLoopedSoundPlayer,
+	layerId: string,
+	soundId: SoundUtils.SoundId,
+	scheduleOptions: SoundLoopScheduleUtils.SoundLoopSchedule?
+): ()
 	assert(type(layerId) == "string", "Bad layerId")
 	assert(SoundUtils.isConvertableToRbxAsset(soundId) or soundId == nil, "Bad soundId")
 	assert(SoundLoopScheduleUtils.isLoopedSchedule(scheduleOptions) or scheduleOptions == nil, "Bad scheduleOptions")
@@ -69,7 +126,15 @@ function LayeredLoopedSoundPlayer:Swap(layerId: string, soundId, scheduleOptions
 	layer:Swap(soundId, scheduleOptions)
 end
 
-function LayeredLoopedSoundPlayer:SwapOnLoop(layerId, soundId, scheduleOptions)
+--[=[
+	Swaps the layer to play on the next loop.
+]=]
+function LayeredLoopedSoundPlayer.SwapOnLoop(
+	self: LayeredLoopedSoundPlayer,
+	layerId: string,
+	soundId: SoundUtils.SoundId,
+	scheduleOptions: SoundLoopScheduleUtils.SoundLoopSchedule?
+): ()
 	assert(type(layerId) == "string", "Bad layerId")
 	assert(SoundUtils.isConvertableToRbxAsset(soundId) or soundId == nil, "Bad soundId")
 
@@ -77,16 +142,32 @@ function LayeredLoopedSoundPlayer:SwapOnLoop(layerId, soundId, scheduleOptions)
 	layer:SwapOnLoop(soundId, scheduleOptions)
 end
 
-function LayeredLoopedSoundPlayer:SwapToSamples(layerId, soundId, scheduleOptions)
+--[=[
+	Swaps the layer to play from a list of samples.
+]=]
+function LayeredLoopedSoundPlayer.SwapToSamples(
+	self: LayeredLoopedSoundPlayer,
+	layerId: string,
+	soundIdList: { SoundUtils.SoundId },
+	scheduleOptions: SoundLoopScheduleUtils.SoundLoopSchedule?
+): ()
 	assert(type(layerId) == "string", "Bad layerId")
-	assert(SoundUtils.isConvertableToRbxAsset(soundId) or soundId == nil, "Bad soundId")
+	assert(type(soundIdList) == "table", "Bad soundIdList")
 	assert(SoundLoopScheduleUtils.isLoopedSchedule(scheduleOptions) or scheduleOptions == nil, "Bad scheduleOptions")
 
 	local layer = self:_getOrCreateLayer(layerId)
-	layer:SwapToSamples(soundId, scheduleOptions)
+	layer:SwapToSamples(soundIdList, scheduleOptions)
 end
 
-function LayeredLoopedSoundPlayer:SwapToChoice(layerId, soundIdList, scheduleOptions)
+--[=[
+	Swaps the layer to play a random choice from a list of samples.
+]=]
+function LayeredLoopedSoundPlayer.SwapToChoice(
+	self: LayeredLoopedSoundPlayer,
+	layerId: string,
+	soundIdList: { SoundUtils.SoundId },
+	scheduleOptions: SoundLoopScheduleUtils.SoundLoopSchedule?
+): ()
 	assert(type(layerId) == "string", "Bad layerId")
 	assert(type(soundIdList) == "table", "Bad soundIdList")
 	assert(SoundLoopScheduleUtils.isLoopedSchedule(scheduleOptions) or scheduleOptions == nil, "Bad scheduleOptions")
@@ -95,23 +176,41 @@ function LayeredLoopedSoundPlayer:SwapToChoice(layerId, soundIdList, scheduleOpt
 	layer:SwapToChoice(soundIdList, scheduleOptions)
 end
 
-function LayeredLoopedSoundPlayer:PlayOnce(layerId, soundIdList, scheduleOptions)
+--[=[
+	Plays the given sound once on the layer.
+]=]
+function LayeredLoopedSoundPlayer.PlayOnce(
+	self: LayeredLoopedSoundPlayer,
+	layerId: string,
+	soundId: SoundUtils.SoundId,
+	scheduleOptions: SoundLoopScheduleUtils.SoundLoopSchedule?
+): ()
 	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)
+	layer:PlayOnce(soundId, scheduleOptions)
 end
 
-function LayeredLoopedSoundPlayer:PlayOnceOnLoop(layerId, soundId, scheduleOptions)
+--[=[
+	Plays the given sound once on the next loop of the layer.
+]=]
+function LayeredLoopedSoundPlayer.PlayOnceOnLoop(
+	self: LayeredLoopedSoundPlayer,
+	layerId: string,
+	soundId: SoundUtils.SoundId,
+	scheduleOptions: SoundLoopScheduleUtils.SoundLoopSchedule?
+): ()
 	assert(type(layerId) == "string", "Bad layerId")
 
 	local layer = self:_getOrCreateLayer(layerId)
 	layer:PlayOnceOnLoop(soundId, scheduleOptions)
 end
 
-function LayeredLoopedSoundPlayer:_getOrCreateLayer(layerId)
+function LayeredLoopedSoundPlayer._getOrCreateLayer(
+	self: LayeredLoopedSoundPlayer,
+	layerId: string
+): LoopedSoundPlayer.LoopedSoundPlayer
 	if self._layers[layerId] then
 		return self._layers[layerId]
 	end
@@ -142,7 +241,7 @@ function LayeredLoopedSoundPlayer:_getOrCreateLayer(layerId)
 	maid:GiveTask(Rx.combineLatest({
 		visible = self:ObserveRenderStepped(),
 		multiplier = self._volumeMultiplier:Observe(),
-	}):Subscribe(function(state)
+	}):Subscribe(function(state: any)
 		layer:SetVolumeMultiplier(state.multiplier * state.visible)
 	end))
 
@@ -158,13 +257,16 @@ function LayeredLoopedSoundPlayer:_getOrCreateLayer(layerId)
 	return layer
 end
 
-function LayeredLoopedSoundPlayer:StopLayer(layerId: string)
+--[=[
+	Stops playback on the given layer.
+]=]
+function LayeredLoopedSoundPlayer.StopLayer(self: LayeredLoopedSoundPlayer, layerId: string): ()
 	assert(type(layerId) == "string", "Bad layerId")
 
 	self._layerMaid[layerId] = nil
 end
 
-function LayeredLoopedSoundPlayer:StopAll()
+function LayeredLoopedSoundPlayer.StopAll(self: LayeredLoopedSoundPlayer): ()
 	self._layerMaid:DoCleaning()
 end
 

package/src/Client/Loops/LoopedSoundPlayer.lua

@@ -8,6 +8,7 @@ local require = require(script.Parent.loader).load(script)
 local RunService = game:GetService("RunService")
 
 local Maid = require("Maid")
+local Observable = require("Observable")
 local Promise = require("Promise")
 local PromiseMaidUtils = require("PromiseMaidUtils")
 local RandomSampler = require("RandomSampler")
@@ -38,7 +39,7 @@ export type LoopedSoundPlayer =
 			_volumeMultiplier: ValueObject.ValueObject<number>,
 			_doSyncSoundPlayback: ValueObject.ValueObject<boolean>,
 			_currentActiveSound: ValueObject.ValueObject<Sound?>,
-			_currentSoundId: ValueObject.ValueObject<(string | number)?>,
+			_currentSoundId: ValueObject.ValueObject<SoundUtils.SoundId?>,
 			_defaultScheduleOptions: SoundLoopScheduleUtils.SoundLoopSchedule,
 			_currentLoopSchedule: ValueObject.ValueObject<SoundLoopScheduleUtils.SoundLoopSchedule>,
 		},
@@ -46,7 +47,7 @@ export type LoopedSoundPlayer =
 	))
 	& SpringTransitionModel.SpringTransitionModel<number>
 
-function LoopedSoundPlayer.new(soundId: (string | number)?, soundParent: Instance?)
+function LoopedSoundPlayer.new(soundId: (string | number)?, soundParent: Instance?): LoopedSoundPlayer
 	assert(soundId == nil or SoundUtils.isConvertableToRbxAsset(soundId), "Bad soundId")
 
 	local self: LoopedSoundPlayer = setmetatable(SpringTransitionModel.new() :: any, LoopedSoundPlayer)
@@ -81,31 +82,59 @@ function LoopedSoundPlayer.new(soundId: (string | number)?, soundParent: Instanc
 	return self
 end
 
-function LoopedSoundPlayer.SetCrossFadeTime(self: LoopedSoundPlayer, crossFadeTime: number)
+--[=[
+	Sets the cross fade time for the LoopedSoundPlayer.
+]=]
+function LoopedSoundPlayer.SetCrossFadeTime(
+	self: LoopedSoundPlayer,
+	crossFadeTime: ValueObject.Mountable<number>
+): () -> ()
 	return self._crossFadeTime:Mount(crossFadeTime)
 end
 
-function LoopedSoundPlayer.SetVolumeMultiplier(self: LoopedSoundPlayer, volume: number)
+--[=[
+	Sets the volume multiplier for the LoopedSoundPlayer.
+]=]
+function LoopedSoundPlayer.SetVolumeMultiplier(self: LoopedSoundPlayer, volume: number): ()
+	assert(type(volume) == "number", "Bad volume")
+
 	self._volumeMultiplier.Value = volume
 end
 
-function LoopedSoundPlayer.SetSoundGroup(self: LoopedSoundPlayer, soundGroup: SoundGroup?)
+--[=[
+	Sets the sound group for the LoopedSoundPlayer.
+]=]
+function LoopedSoundPlayer.SetSoundGroup(
+	self: LoopedSoundPlayer,
+	soundGroup: ValueObject.Mountable<SoundGroup?>
+): () -> ()
 	return self._soundGroup:Mount(soundGroup)
 end
 
-function LoopedSoundPlayer.SetBPM(self: LoopedSoundPlayer, bpm: number?)
+--[=[
+	Sets the BPM for syncing sound playback.
+]=]
+function LoopedSoundPlayer.SetBPM(self: LoopedSoundPlayer, bpm: number?): ()
 	assert(type(bpm) == "number" or bpm == nil, "Bad bpm")
 
 	self._bpm.Value = bpm
 end
 
-function LoopedSoundPlayer.SetSoundParent(self: LoopedSoundPlayer, parent: Instance?)
+--[=[
+	Sets the parent instance for the sound.
+]=]
+function LoopedSoundPlayer.SetSoundParent(self: LoopedSoundPlayer, parent: Instance?): ()
 	self._soundParent.Value = parent
 end
 
-function LoopedSoundPlayer.Swap(self: LoopedSoundPlayer, soundId, loopSchedule)
+function LoopedSoundPlayer.Swap(
+	self: LoopedSoundPlayer,
+	soundId: SoundUtils.SoundId,
+	loopSchedule: SoundLoopScheduleUtils.SoundLoopSchedule?
+): ()
 	assert(SoundUtils.isConvertableToRbxAsset(soundId) or soundId == nil, "Bad soundId")
 	loopSchedule = self:_convertToLoopedSchedule(loopSchedule)
+	assert(loopSchedule ~= nil, "Bad loopSchedule")
 
 	local maid = Maid.new()
 
@@ -117,11 +146,14 @@ function LoopedSoundPlayer.Swap(self: LoopedSoundPlayer, soundId, loopSchedule)
 	self._maid._swappingTo = maid
 end
 
-function LoopedSoundPlayer.SetDoSyncSoundPlayback(self: LoopedSoundPlayer, doSyncSoundPlayback: boolean)
+--[=[
+	Sets whether to sync sound playback to BPM.
+]=]
+function LoopedSoundPlayer.SetDoSyncSoundPlayback(self: LoopedSoundPlayer, doSyncSoundPlayback: boolean): ()
 	self._doSyncSoundPlayback.Value = doSyncSoundPlayback
 end
 
-function LoopedSoundPlayer._setupRender(self: LoopedSoundPlayer)
+function LoopedSoundPlayer._setupRender(self: LoopedSoundPlayer): ()
 	self._maid:GiveTask(self._currentSoundId
 		:ObserveBrio(function(value)
 			return value ~= nil
@@ -132,17 +164,18 @@ function LoopedSoundPlayer._setupRender(self: LoopedSoundPlayer)
 			end
 
 			local maid = brio:ToMaid()
-			local soundId = brio:GetValue()
+			local soundId: SoundUtils.SoundId = brio:GetValue() :: any
 
 			maid:GiveTask(self:_renderSoundPlayer(soundId))
 		end))
 end
 
-function LoopedSoundPlayer._renderSoundPlayer(self: LoopedSoundPlayer, soundId)
+function LoopedSoundPlayer._renderSoundPlayer(self: LoopedSoundPlayer, soundId: SoundUtils.SoundId): Maid.Maid
 	local maid = Maid.new()
 
 	local renderMaid = Maid.new()
-	local soundPlayer = renderMaid:Add(SimpleLoopedSoundPlayer.new(soundId))
+	local soundPlayer: SimpleLoopedSoundPlayer.SimpleLoopedSoundPlayer =
+		renderMaid:Add(SimpleLoopedSoundPlayer.new(soundId))
 	soundPlayer:SetTransitionTime(self._crossFadeTime)
 
 	renderMaid:GiveTask(self._soundGroup:Observe():Subscribe(function(soundGroup)
@@ -235,7 +268,11 @@ function LoopedSoundPlayer._renderSoundPlayer(self: LoopedSoundPlayer, soundId)
 	return maid
 end
 
-function LoopedSoundPlayer._setupLoopScheduling(self: LoopedSoundPlayer, soundPlayer, loopSchedule)
+function LoopedSoundPlayer._setupLoopScheduling(
+	self: LoopedSoundPlayer,
+	soundPlayer: SimpleLoopedSoundPlayer.SimpleLoopedSoundPlayer,
+	loopSchedule: SoundLoopScheduleUtils.SoundLoopSchedule
+): Maid.Maid
 	local maid = Maid.new()
 
 	if loopSchedule.maxLoops then
@@ -270,9 +307,14 @@ function LoopedSoundPlayer._setupLoopScheduling(self: LoopedSoundPlayer, soundPl
 	return maid
 end
 
-function LoopedSoundPlayer.SwapToSamples(self: LoopedSoundPlayer, soundIdList, loopSchedule)
+function LoopedSoundPlayer.SwapToSamples(
+	self: LoopedSoundPlayer,
+	soundIdList: { SoundUtils.SoundId },
+	loopSchedule: SoundLoopScheduleUtils.SoundLoopSchedule?
+): ()
 	assert(type(soundIdList) == "table", "Bad soundIdList")
 	loopSchedule = self:_convertToLoopedSchedule(loopSchedule)
+	assert(loopSchedule ~= nil, "Bad loopSchedule")
 
 	local loopMaid = Maid.new()
 
@@ -289,9 +331,17 @@ function LoopedSoundPlayer.SwapToSamples(self: LoopedSoundPlayer, soundIdList, l
 	self._maid._swappingTo = loopMaid
 end
 
-function LoopedSoundPlayer.SwapToChoice(self: LoopedSoundPlayer, soundIdList, loopSchedule)
+--[=[
+	Swaps to a random choice from the provided list of sound IDs on loop.
+]=]
+function LoopedSoundPlayer.SwapToChoice(
+	self: LoopedSoundPlayer,
+	soundIdList: { SoundUtils.SoundId },
+	loopSchedule: SoundLoopScheduleUtils.SoundLoopSchedule?
+): ()
 	assert(type(soundIdList) == "table", "Bad soundIdList")
 	loopSchedule = self:_convertToLoopedSchedule(loopSchedule)
+	assert(loopSchedule ~= nil, "Bad loopSchedule")
 
 	local loopMaid = Maid.new()
 
@@ -307,33 +357,64 @@ function LoopedSoundPlayer.SwapToChoice(self: LoopedSoundPlayer, soundIdList, lo
 	self._maid._swappingTo = loopMaid
 end
 
-function LoopedSoundPlayer.PlayOnce(self: LoopedSoundPlayer, soundId, loopSchedule)
+--[=[
+	Plays the sound once
+]=]
+function LoopedSoundPlayer.PlayOnce(
+	self: LoopedSoundPlayer,
+	soundId: SoundUtils.SoundId,
+	loopSchedule: SoundLoopScheduleUtils.SoundLoopSchedule?
+): ()
 	assert(SoundUtils.isConvertableToRbxAsset(soundId) or soundId == nil, "Bad soundId")
 	loopSchedule = self:_convertToLoopedSchedule(loopSchedule)
+	assert(loopSchedule ~= nil, "Bad loopSchedule")
 
 	self:Swap(soundId, SoundLoopScheduleUtils.maxLoops(1, loopSchedule))
 end
 
-function LoopedSoundPlayer.SwapOnLoop(self: LoopedSoundPlayer, soundId, loopSchedule)
+--[=[
+	Swaps the sound on the next loop
+]=]
+function LoopedSoundPlayer.SwapOnLoop(
+	self: LoopedSoundPlayer,
+	soundId: SoundUtils.SoundId,
+	loopSchedule: SoundLoopScheduleUtils.SoundLoopSchedule?
+): ()
 	assert(SoundUtils.isConvertableToRbxAsset(soundId) or soundId == nil, "Bad soundId")
 	loopSchedule = self:_convertToLoopedSchedule(loopSchedule)
+	assert(loopSchedule ~= nil, "Bad loopSchedule")
 
 	self:Swap(soundId, SoundLoopScheduleUtils.onNextLoop(loopSchedule))
 end
 
-function LoopedSoundPlayer.PlayOnceOnLoop(self: LoopedSoundPlayer, soundId, loopSchedule)
+--[=[
+	Plays the sound once on the next loop
+]=]
+function LoopedSoundPlayer.PlayOnceOnLoop(
+	self: LoopedSoundPlayer,
+	soundId: SoundUtils.SoundId,
+	loopSchedule: SoundLoopScheduleUtils.SoundLoopSchedule?
+): ()
 	assert(SoundUtils.isConvertableToRbxAsset(soundId) or soundId == nil, "Bad soundId")
 	loopSchedule = self:_convertToLoopedSchedule(loopSchedule)
+	assert(loopSchedule ~= nil, "Bad loopSchedule")
 
 	self:PlayOnce(soundId, SoundLoopScheduleUtils.onNextLoop(loopSchedule))
 end
 
-function LoopedSoundPlayer._convertToLoopedSchedule(self: LoopedSoundPlayer, loopSchedule)
+function LoopedSoundPlayer._convertToLoopedSchedule(
+	self: LoopedSoundPlayer,
+	loopSchedule: SoundLoopScheduleUtils.SoundLoopSchedule?
+): SoundLoopScheduleUtils.SoundLoopSchedule
 	assert(SoundLoopScheduleUtils.isLoopedSchedule(loopSchedule) or loopSchedule == nil, "Bad loopSchedule")
 	return loopSchedule or self._defaultScheduleOptions
 end
 
-function LoopedSoundPlayer._scheduleFirstPlay(self: LoopedSoundPlayer, loopSchedule, callback)
+function LoopedSoundPlayer._scheduleFirstPlay(
+	self: LoopedSoundPlayer,
+	loopSchedule: SoundLoopScheduleUtils.SoundLoopSchedule,
+	callback
+): Maid.Maid
 	assert(SoundLoopScheduleUtils.isLoopedSchedule(loopSchedule), "Bad loopSchedule")
 	assert(type(callback) == "function", "Bad callback")
 
@@ -374,7 +455,10 @@ function LoopedSoundPlayer._scheduleFirstPlay(self: LoopedSoundPlayer, loopSched
 	return maid
 end
 
-function LoopedSoundPlayer.StopAfterLoop(self: LoopedSoundPlayer)
+--[=[
+	Stops playback after the current loop finishes.
+]=]
+function LoopedSoundPlayer.StopAfterLoop(self: LoopedSoundPlayer): ()
 	local swapMaid = Maid.new()
 
 	swapMaid:GiveTask(self._currentSoundLooped:Connect(function()
@@ -386,7 +470,10 @@ function LoopedSoundPlayer.StopAfterLoop(self: LoopedSoundPlayer)
 	self._maid._swappingTo = swapMaid
 end
 
-function LoopedSoundPlayer._observeActiveSoundFinishLoop(self: LoopedSoundPlayer, maxWaitTime)
+function LoopedSoundPlayer._observeActiveSoundFinishLoop(
+	self: LoopedSoundPlayer,
+	maxWaitTime: number
+): Observable.Observable<()>
 	local startTime = os.clock()
 
 	return self._currentActiveSound:Observe():Pipe({
@@ -430,6 +517,9 @@ function LoopedSoundPlayer._observeActiveSoundFinishLoop(self: LoopedSoundPlayer
 	}) :: any
 end
 
+--[=[
+	Promises that resolve when the current loop is done.
+]=]
 function LoopedSoundPlayer.PromiseLoopDone(self: LoopedSoundPlayer): Promise.Promise<()>
 	local promise = self._maid:GivePromise(Promise.new())
 
@@ -442,11 +532,17 @@ function LoopedSoundPlayer.PromiseLoopDone(self: LoopedSoundPlayer): Promise.Pro
 	return promise
 end
 
+--[=[
+	Promises that never resolve, keeping the sound player alive.
+]=]
 function LoopedSoundPlayer.PromiseSustain(_self: LoopedSoundPlayer): Promise.Promise<()>
 	-- Never resolve (?)
 	return Promise.new()
 end
 
+--[=[
+	Gets the currently active sound instance.
+]=]
 function LoopedSoundPlayer.GetSound(self: LoopedSoundPlayer): Sound?
 	return self._currentActiveSound.Value
 end

package/src/Client/Loops/SimpleLoopedSoundPlayer.lua

@@ -1,4 +1,4 @@
---!nonstrict
+--!strict
 --[=[
 	@class SimpleLoopedSoundPlayer
 ]=]
@@ -16,8 +16,19 @@ local SimpleLoopedSoundPlayer = setmetatable({}, TimedTransitionModel)
 SimpleLoopedSoundPlayer.ClassName = "SimpleLoopedSoundPlayer"
 SimpleLoopedSoundPlayer.__index = SimpleLoopedSoundPlayer
 
-function SimpleLoopedSoundPlayer.new(soundId)
-	local self = setmetatable(TimedTransitionModel.new(), SimpleLoopedSoundPlayer)
+export type SimpleLoopedSoundPlayer =
+	typeof(setmetatable(
+		{} :: {
+			Sound: Sound,
+			_volumeMultiplier: ValueObject.ValueObject<number>,
+			_maxVolume: number,
+		},
+		{} :: typeof({ __index = SimpleLoopedSoundPlayer })
+	))
+	& TimedTransitionModel.TimedTransitionModel
+
+function SimpleLoopedSoundPlayer.new(soundId: SoundUtils.SoundId): SimpleLoopedSoundPlayer
+	local self: SimpleLoopedSoundPlayer = setmetatable(TimedTransitionModel.new() :: any, SimpleLoopedSoundPlayer)
 
 	self.Sound = self._maid:Add(SoundUtils.createSoundFromId(soundId))
 	self.Sound.Looped = true
@@ -32,7 +43,7 @@ function SimpleLoopedSoundPlayer.new(soundId)
 	self._maid:GiveTask(Rx.combineLatest({
 		visible = self:ObserveRenderStepped(),
 		multiplier = self._volumeMultiplier:Observe(),
-	}):Subscribe(function(state)
+	}):Subscribe(function(state: any)
 		self.Sound.Volume = state.visible * self._maxVolume * state.multiplier
 	end))
 
@@ -45,22 +56,35 @@ function SimpleLoopedSoundPlayer.new(soundId)
 	return self
 end
 
-function SimpleLoopedSoundPlayer:SetSoundGroup(soundGroup)
+--[=[
+	Sets the SoundGroup of the internal Sound.
+	@param soundGroup SoundGroup?
+]=]
+function SimpleLoopedSoundPlayer.SetSoundGroup(self: SimpleLoopedSoundPlayer, soundGroup: SoundGroup?): ()
 	assert(typeof(soundGroup) == "Instance" or soundGroup == nil, "Bad soundGroup")
 
 	self.Sound.SoundGroup = soundGroup
 end
 
-function SimpleLoopedSoundPlayer:SetVolumeMultiplier(volume)
+--[=[
+	Sets the volume multiplier for the sound player.
+]=]
+function SimpleLoopedSoundPlayer.SetVolumeMultiplier(self: SimpleLoopedSoundPlayer, volume: number): ()
 	self._volumeMultiplier.Value = volume
 end
 
-function SimpleLoopedSoundPlayer:PromiseSustain()
+--[=[
+	Promises indefinitely until the sound player is destroyed.
+]=]
+function SimpleLoopedSoundPlayer.PromiseSustain(self: SimpleLoopedSoundPlayer): Promise.Promise<()>
 	-- Never resolve
-	return Promise.new()
+	return self._maid:GivePromise(Promise.new())
 end
 
-function SimpleLoopedSoundPlayer:PromiseLoopDone()
+--[=[
+	Promises until the current loop is done.
+]=]
+function SimpleLoopedSoundPlayer.PromiseLoopDone(self: SimpleLoopedSoundPlayer): Promise.Promise<()>
 	return SoundPromiseUtils.promiseLooped(self.Sound)
 end