Add source:pause() and source:resume()

slam/README.md

@@ -1,16 +1,14 @@
 SLAM
 ====
-... is the **Simple [LOVE] Audio Manager** formerly known as the
+... is the **Simple [LOVE] Audio Manager** formerly known as the **Benignly
-**Benignly Designed Sound Manager.** It's a minimally invasive
+Designed Sound Manager.** It's a minimally invasive augmentation of [LOVE]'s
-augmentation of [LOVE]'s audio module. In contrast to sources that
+audio module. In contrast to sources that can only have one simultaneous
-can only have one simultaneous playing instance, SLAM sources
+playing instance, SLAM sources create *instances* when played. This way you can
-create *instances* when played. This way you can play one source
+play one source multiple times at once. Each instance will inherit the settings
-multiple times at once. Each instance will inherit the settings
+(volume, speed, looping, ...) of it's SLAM source, but can override them.
-(volume, speed, looping, ...) of it's SLAM source, but can
-override them.
 
-SLAM also features tags, which can be used to modify a number of
+SLAM also features tags, which can be used to modify a number of sources at the
-sources at the same time.
+same time.
 
 Example
 -------
@@ -39,16 +37,17 @@ Reference
     source = love.audio.newSource(what, how)
 
 Returns a new SLAM source. Accepts the same parameters as
-[love.audio.newSource](http://love2d.org/wiki/love.audio.newSource), with one major
+[love.audio.newSource](http://love2d.org/wiki/love.audio.newSource), with one
-difference: `what` can be a table, in which case each new playing instance will
+major difference: `what` can be a table, in which case each new playing
-pick an item of that table at random.
+instance will pick an item of that table at random.
 
 
     instance = love.audio.play(source)
     instance = source:play()
 
-Plays a source and returns a handle to the player instance. Instances will inherit
+Plays a source, removes all paused instances and returns a handle to the player
-the settings (looping, pitch, volume) of `source`.
+instance. Instances will inherit the settings (looping, pitch, volume) of
+`source`.
 
 
     love.audio.stop(source)
@@ -62,6 +61,17 @@ Stops all playing instances of a source.
 Stops all playing instances.
 
 
+    source:pause()
+
+Pauses all playing instances of a source.
+
+
+    source:resume()
+
+Resumes all paused instances of a source. **Note:** source:play() clears paused
+instances from a paused source.
+
+
     source:isStatic()
 
 Returns `true` if the source is static, `false` otherwise.
@@ -74,13 +84,14 @@ Returns `true` if the source is static, `false` otherwise.
     volume = source:getVolume()
     source:setVolume(volume)
 
-Sets properties for all instances. Affects playing instances immediately. For details
+Sets properties for all instances. Affects playing instances immediately. For
-on the parameters, see the [LOVE wiki](http://love2d.org/wiki/Source).
+details on the parameters, see the [LOVE wiki](http://love2d.org/wiki/Source).
 
 
 ### Instances
 
-All functions that affect LOVE Sources can be applied to SLAM instances. These are:
+All functions that affect LOVE Sources can be applied to SLAM instances. These
+are:
 
     love.audio.pause(instance)
     instance:pause()
@@ -118,8 +129,8 @@ See the [LOVE wiki](http://love2d.org/wiki/Source) for details.
 
 ### Tags
 
-With tags you can group several sources together and call functions upon them. A
+With tags you can group several sources together and call functions upon them.
-simple example might be this:
+A simple example:
 
     -- add some stuff to the background tag
     drums:addTags('music')
@@ -138,7 +149,8 @@ simple example might be this:
 
     source:addTags(tag, ...)
 
-Adds one or more tags to a source. By default, all sources are member of the tag `all`.
+Adds one or more tags to a source. By default, all sources are member of the
+tag `all`.
 
 
     source:removeTags(tag, ...)

slam/slam.lua

@@ -32,7 +32,7 @@ local stop = love.audio.stop
 ------------------
 local Source = {}
 Source.__index = Source
-Source.__newindex = error
+Source.__newindex = function(_,k) error(('Cannot write key %s'):format(tostring(k))) end
 
 local function remove_stopped(sources)
 	local remove = {}
@@ -44,17 +44,18 @@ local function remove_stopped(sources)
 	end
 end
 
-local function get_what(what)
+local function get_target(target)
-	if type(what) == 'table' then
+	if type(target) == 'table' then
-		return what[math.random(1,#what)]
+		return target[math.random(1,#target)]
 	end
-	return what
+	return target
 end
 
 local play_instance, stop_instance
 function Source:play()
 	remove_stopped(self.instances)
-	local instance = newInstance(get_what(self.what), self.how)
+	if self._paused then self:stop() end
+	local instance = newInstance(get_target(self.target), self.how)
 
 	-- overwrite instance:stop() and instance:play()
 	if not (play_instance and stop_instance) then
@@ -81,9 +82,26 @@ function Source:stop()
 	for s in pairs(self.instances) do
 		s:stop()
 	end
+	self._paused = false
 	self.instances = {}
 end
 
+function Source:pause()
+	if self._paused then return end
+	for s in pairs(self.instances) do
+		s:pause()
+	end
+	self._paused = true
+end
+
+function Source:resume()
+	if not self._paused then return end
+	for s in pairs(self.instances) do
+		s:resume()
+	end
+	self._paused = false
+end
+
 function Source:addTags(tag, ...)
 	if not tag then return end
 	love.audio.tags[tag][self] = self
@@ -119,29 +137,30 @@ Source.isLooping = Source.getLooping
 --------------------------
 -- love.audio interface --
 --------------------------
-function love.audio.newSource(what, how)
+function love.audio.newSource(target, how)
 	local s = {
-		what      = what,
+		_paused   = false,
+		target    = target,
 		how       = how,
 		instances = {},
 		looping   = false,
 		pitch     = 1,
 		volume    = 1,
 	}
-	if how == 'static' and type(what) == 'string' then
+	if how == 'static' and type(target) == 'string' then
-		s.what = love.sound.newSoundData(what)
+		s.target = love.sound.newSoundData(target)
 	end
 	love.audio.tags.all[s] = s
 	return setmetatable(s, Source)
 end
 
-function love.audio.play(what)
+function love.audio.play(source)
-	assert(what and what.instances, "Can only play source objects.")
+	assert(source and source.instances, "Can only play source objects.")
-	return what:play()
+	return source:play()
 end
 
-function love.audio.stop(what)
+function love.audio.stop(source)
-	if what and what.stop then return what:stop() end
+	if source and source.stop then return source:stop() end
 	stop()
 end